rtClient.collections
SDK methods for curated collections - grouping smart products into campaigns.
A Collection is a curated, ordered grouping of smart products - a campaign. On-the-record models each open-letter campaign ("Dear Stacks", "Dear Bitcoin") as a Collection; its items are the smart products that belong to it. rtClient.collections backs collection and item CRUD. All methods resolve to ApiResponse<T> (lists to PaginatedResponse<T>).
Collections
rtClient.collections.listCollections(params?)
List collections. Returns PaginatedResponse<Collection> - unwrap data.items. Accepts CollectionListParams (appId, ownerAddress, isActive, plus paging).
const res = await rtClient.collections.listCollections({ appId: APP_ID, isActive: true });
const collections = res.data.items;rtClient.collections.getCollectionById(id) / getCollectionBySlug(slug)
Fetch one collection by numeric id or by slug. Both return ApiResponse<Collection>.
const { data: collection } = await rtClient.collections.getCollectionBySlug("dear-stacks");
console.log(collection.name, collection.itemCount);rtClient.collections.createCollection(input) / updateCollection(id, patch) / deleteCollection(id)
Create, patch, or delete a collection. CreateCollectionInput requires name, ownerAddress, and sourceAppId (the slug is derived from the name when omitted); optional description, imageUrl, theme, metadata, rules.
const { data: collection } = await rtClient.collections.createCollection({
name: "Dear Stacks",
description: "An open letter to the Stacks community",
ownerAddress: user.stxAddress,
sourceAppId: APP_ID,
});Items
A CollectionItem links an entity (a smart product) into a collection at a position. In AddCollectionItemInput, entityType is a free-form, server-defined string naming the kind of entity, and entityId is its numeric id.
// Add a smart product to a collection at position 0
const { data: item } = await rtClient.collections.addItem(collectionId, {
entityType, // server-defined entity kind
entityId: productId,
position: 0,
});
// List items (paginated)
const res = await rtClient.collections.listItems(collectionId, { limit: 50 });
const items = res.data.items;
// Reorder, patch, or remove
await rtClient.collections.reorderItems(collectionId, [itemId3, itemId1, itemId2]);
await rtClient.collections.updateItem(collectionId, item.id, { position: 2 });
await rtClient.collections.removeItem(collectionId, item.id);rtClient.collections.getCollectionsForProduct(productId)
Reverse lookup - every collection a given smart product belongs to. Returns ApiResponse<Collection[]>.
const { data: collections } = await rtClient.collections.getCollectionsForProduct(productId);