Stickers (SDK)

Stickers are optional visual overlays attached to a DRAFT smart product. When a sticker is attached, a STICKER_ARTIST contribution is materialized automatically at the sticker's configured royaltyPercentage.

Methods

`rtClient.stickers.listStickers(params?)`

List stickers. Returns PaginatedResponse<Sticker> - unwrap data.items.

const res = await rtClient.stickers.listStickers({ tags: "botanical", limit: 20 });
const stickers = res.data.items;

Filters:

Filter	Type	Description
`tags`	`string`	Filter by tag
`artist`	`string`	Filter by artist
`includeInactive`	`boolean`	Include retired stickers
`includeSvg`	`boolean`	Embed each sticker's `svgContent`
`submissionStatus`	`'DRAFT' \| 'SUBMITTED' \| 'APPROVED' \| 'REJECTED'`	Filter by approval state
`includeUnapproved`	`boolean`	Owner/operator views: include non-approved stickers (default false)
`styleSetId`	`number`	Filter to a brand/line
`page` / `limit`	`number`	Pagination

`rtClient.stickers.getSticker(id)`

Get a sticker by numeric id (includes svgContent). Returns ApiResponse<Sticker>.

const { data: sticker } = await rtClient.stickers.getSticker(12);
console.log(sticker.artistUserId);      // FK to the artist User
console.log(sticker.royaltyPercentage); // STICKER_ARTIST royalty rate

Attaching a sticker

Sticker placement lives on the smart product, via rtClient.smartProducts.addSticker. Each attach creates a ProductSticker row plus a matching STICKER_ARTIST ProductContribution, and takes a placement (x, y, and optional scale / rotation).

const { data: placement } = await rtClient.smartProducts.addSticker(productId, {
  stickerId: 12,
  x: 100,
  y: 200,
  scale: 1,
  rotation: 0,
});

A product can carry multiple sticker placements. Update or remove one with rtClient.smartProducts.updateStickerPlacement(productId, rowId, patch) / removeSticker(productId, rowId). All three reject once the product has deployed (status is not DRAFT) - the on-chain creator-info map would diverge. See rtClient.smartProducts.

Placement helpers

A placement is { x, y, scale, rotation } in the template's canvas coordinates, and every Style may carry a stickerZone ({ x, y, width, height, anchor? }) bounding where a sticker may sit. The SDK exports four pure helpers for an editor:

Helper	What it does
`defaultPlacement(zone)`	Where a new sticker starts: the zone's `anchor` (the template's suggested spot) when it lies inside the zone, otherwise the centre of the zone, at scale 1 and rotation 0
`isWithinZone(placement, zone, stickerWidth, stickerHeight)`	Whether the scaled sticker stays inside the zone
`clampToZone(placement, zone, stickerWidth, stickerHeight)`	A new placement moved back inside the zone, keeping scale and rotation
`buildStickerTransform(placement, stickerWidth?, stickerHeight?)`	The SVG `transform` string the server applies, so a client preview matches the render (translate, then rotate, then scale; rotation omitted at 0 and scale at 1)

import { defaultPlacement, clampToZone } from "@rising-tide/sdk";

const start = defaultPlacement(style.stickerZone!);
const next = clampToZone({ ...start, x: start.x + 20 }, style.stickerZone!, 100, 100);

StickerEditor and StickerPicker in @rising-tide/ui/react are ready-made editor components built on these.

How sticker rendering works

At render time the server loads the sticker SVG, rewrites its internal ids to avoid conflicts, and composites it onto the base style-set SVG - returning a single merged SVG.