Collections

Collections group tones and constraints into a named bundle (e.g. "Customer support tone of voice"). They are non-versioned, and visibility is set inline through the main update(). Sub-resource endpoints (listConstraints, setConstraints, listTones, setTones) let you manage membership without re-sending the whole collection.

Methods

list

client.collections.list(params?: ListParams): Promise<Page<CollectionSummary>>

List public collections 
const page = await client.collections.list({ scope: "public", pageSize: 12 });
return {
  total: page.total,
  items: page.items.map((c) => ({ id: c.id, name: c.name, tags: c.tags })),
};

listAll

client.collections.listAll(params?: ListParams): AsyncIterable<CollectionSummary>

Iterate the public collections feed 
const names = [];
for await (const collection of client.collections.listAll({ scope: "public", pageSize: 12 })) {
  names.push(collection.name);
  if (names.length >= 12) break;
}
return names;

get

client.collections.get(id: string): Promise<Collection>

Detail responses include the constraint and tone items inline (under items and toneItems).

Fetch a public collection 
const page = await client.collections.list({ scope: "public", pageSize: 6 });
const first = page.items[0];
if (!first) return { empty: true };

const collection = await client.collections.get(first.id);
return {
  id: collection.id,
  name: collection.name,
  description: collection.description,
  tags: collection.tags,
  constraintCount: collection.items.length,
  toneCount: collection.toneItems.length,
};

create

client.collections.create(input: CollectionCreateInput): Promise<CollectionCreateResponse>

Pass constraintIds and/or toneIds to seed the collection with members. Names must be unique per user.

⚠️ Writes to your account. Cleans up after itself.
Create then delete 
const created = await client.collections.create({
  name: `docs-demo-collection-${Date.now()}`,
  description: "Created from the docs site.",
  isPublic: false,
  tags: ["demo"],
});
await client.collections.delete(created.id);
return created;

update

client.collections.update(id: string, input: CollectionUpdateInput): Promise<void>

Updates name, description, tags, or visibility (no separate visibility endpoint).

⚠️ Writes to your account. Cleans up after itself.
Create, update, clean up 
const created = await client.collections.create({
  name: `docs-demo-${Date.now()}`,
  description: "original",
  isPublic: false,
});
await client.collections.update(created.id, {
  name: `docs-demo-updated-${Date.now()}`,
  description: "updated",
  tags: ["updated"],
  isPublic: true,
});
const detail = await client.collections.get(created.id);
await client.collections.delete(created.id);
return {
  name: detail.name,
  description: detail.description,
  tags: detail.tags,
  isPublic: detail.isPublic,
};

delete

client.collections.delete(id: string): Promise<void>

⚠️ Writes to your account. Cleans up after itself.
Create then delete 
const created = await client.collections.create({ name: `docs-demo-${Date.now()}` });
await client.collections.delete(created.id);
try {
  await client.collections.get(created.id);
  return { deleted: false };
} catch (err) {
  if (err instanceof PromptyNotFoundError) return { deleted: true };
  throw err;
}

vote

client.collections.vote(id: string, value: 1 | -1): Promise<void>

⚠️ Writes to your account. Cleans up after itself.
Vote on your own collection 
const created = await client.collections.create({ name: `docs-demo-vote-${Date.now()}` });
await client.collections.vote(created.id, 1);
const detail = await client.collections.get(created.id);
await client.collections.delete(created.id);
return { upvotes: detail.upvotes, userVote: detail.userVote };

unvote

client.collections.unvote(id: string): Promise<void>

⚠️ Writes to your account. Cleans up after itself.
Vote, unvote, clean up 
const created = await client.collections.create({ name: `docs-demo-unvote-${Date.now()}` });
await client.collections.vote(created.id, -1);
await client.collections.unvote(created.id);
const detail = await client.collections.get(created.id);
await client.collections.delete(created.id);
return { downvotes: detail.downvotes, userVote: detail.userVote };

toggleFavorite

client.collections.toggleFavorite(id: string): Promise<{ favorited: boolean }>

⚠️ Writes to your account. Cleans up after itself.
Toggle on, off, clean up 
const created = await client.collections.create({ name: `docs-demo-fav-${Date.now()}` });
const a = await client.collections.toggleFavorite(created.id);
const b = await client.collections.toggleFavorite(created.id);
await client.collections.delete(created.id);
return { firstToggle: a.favorited, secondToggle: b.favorited };

listConstraints

client.collections.listConstraints(id: string): Promise<readonly CollectionConstraintRef[]>

Returns the constraints currently in the collection. Each item carries the join-row id, the underlying constraintId, and the constraint text.

⚠️ Writes to your account. Cleans up after itself.
Build a collection with one constraint, list it, clean up 
const constraint = await client.constraints.create({
  text: `docs-demo-c ${Date.now()}`,
  isPublic: false,
});
const collection = await client.collections.create({
  name: `docs-demo-coll-${Date.now()}`,
  isPublic: false,
  constraintIds: [constraint.id],
});

const constraintsInCollection = await client.collections.listConstraints(collection.id);

await client.collections.delete(collection.id);
await client.constraints.delete(constraint.id);

return constraintsInCollection;

setConstraints

client.collections.setConstraints(id: string, constraintIds: readonly string[]): Promise<void>

Replaces the entire constraint set for the collection - pass an empty array to clear them.

⚠️ Writes to your account. Cleans up after itself.
Add, replace, clear, clean up 
const c1 = await client.constraints.create({ text: `docs-c1 ${Date.now()}`, isPublic: false });
const c2 = await client.constraints.create({ text: `docs-c2 ${Date.now()}`, isPublic: false });
const collection = await client.collections.create({ name: `docs-coll-${Date.now()}`, isPublic: false });

await client.collections.setConstraints(collection.id, [c1.id]);
const after1 = (await client.collections.listConstraints(collection.id)).length;

await client.collections.setConstraints(collection.id, [c1.id, c2.id]);
const after2 = (await client.collections.listConstraints(collection.id)).length;

await client.collections.setConstraints(collection.id, []);
const after3 = (await client.collections.listConstraints(collection.id)).length;

await client.collections.delete(collection.id);
await client.constraints.delete(c1.id);
await client.constraints.delete(c2.id);

return { afterFirstSet: after1, afterSecondSet: after2, afterClear: after3 };

listTones

client.collections.listTones(id: string): Promise<readonly CollectionToneRef[]>

Same shape as listConstraints but for the collection's tone items. Each entry carries the join-row id, toneId, and tone label.

⚠️ Writes to your account. Cleans up after itself.
Build a collection with one tone, list it, clean up 
const tone = await client.tones.create({ label: `docs-tone-${Date.now()}`, isPublic: false });
const collection = await client.collections.create({
  name: `docs-coll-${Date.now()}`,
  isPublic: false,
  toneIds: [tone.id],
});

const tonesInCollection = await client.collections.listTones(collection.id);

await client.collections.delete(collection.id);
await client.tones.delete(tone.id);

return tonesInCollection;

setTones

client.collections.setTones(id: string, toneIds: readonly string[]): Promise<void>

Replaces the entire tone set for the collection.

⚠️ Writes to your account. Cleans up after itself.
Add, replace, clear, clean up 
const t1 = await client.tones.create({ label: `docs-t1-${Date.now()}`, isPublic: false });
const t2 = await client.tones.create({ label: `docs-t2-${Date.now()}`, isPublic: false });
const collection = await client.collections.create({ name: `docs-coll-${Date.now()}`, isPublic: false });

await client.collections.setTones(collection.id, [t1.id]);
const after1 = (await client.collections.listTones(collection.id)).length;

await client.collections.setTones(collection.id, [t1.id, t2.id]);
const after2 = (await client.collections.listTones(collection.id)).length;

await client.collections.setTones(collection.id, []);
const after3 = (await client.collections.listTones(collection.id)).length;

await client.collections.delete(collection.id);
await client.tones.delete(t1.id);
await client.tones.delete(t2.id);

return { afterFirstSet: after1, afterSecondSet: after2, afterClear: after3 };