Constraint collections
A constraint collection groups
constraints into a named bundle (e.g.
"Customer support guardrails"). Collections are non-versioned,
scoped per building block, and reachable through
client.constraints.collections. The platform exposes them
at /api/v1/constraints/collections; visibility is set
inline via update(). Membership is managed by the uniform
listItems(id) / setItems(id, itemIds) pair.
client.collections.* namespace has been
removed - it pointed at /api/v1/collections/*, which does
not exist on the platform and always returned 404. Use
client.tones.collections
for tone collections and client.constraints.collections
for constraint collections. See the project
CHANGELOG
for the full migration note.
list
client.constraints.collections.list(params?: ListParams): Promise<Page<CollectionSummary>>
Each CollectionSummary carries id,
name, description, tags,
itemCount, and the standard engagement fields.
const page = await client.constraints.collections.list({ scope: "public", pageSize: 12 });
return {
total: page.total,
items: page.items.map((c) => ({
id: c.id,
name: c.name,
itemCount: c.itemCount,
tags: c.tags,
})),
};listAll
client.constraints.collections.listAll(params?: ListParams): AsyncIterable<CollectionSummary>
const names = [];
for await (const collection of client.constraints.collections.listAll({ scope: "public", pageSize: 12 })) {
names.push(collection.name);
if (names.length >= 12) break;
}
return names;get
client.constraints.collections.get(id: string): Promise<ConstraintCollection>
Detail responses include the constraint members inline as
items: an array of ConstraintCollectionItem
objects, each carrying the join-row id, the underlying
constraintId, and the constraint text.
const page = await client.constraints.collections.list({ scope: "public", pageSize: 6 });
const first = page.items[0];
if (!first) return { empty: true };
const collection = await client.constraints.collections.get(first.id);
return {
id: collection.id,
name: collection.name,
description: collection.description,
tags: collection.tags,
itemCount: collection.items.length,
items: collection.items.map((it) => ({ constraintId: it.constraintId, text: it.text })),
};create
client.constraints.collections.create(input: CollectionCreateInput): Promise<CollectionCreateResponse>
Pass itemIds to seed the collection with constraints. The
previous separate constraintIds field has been removed;
itemIds is the single, uniform input across both tone and
constraint collections.
const created = await client.constraints.collections.create({
name: `docs-demo-constraint-coll-${Date.now()}`,
description: "Created from the docs site.",
isPublic: false,
tags: ["demo"],
});
await client.constraints.collections.delete(created.id);
return created;update
client.constraints.collections.update(id: string, input: CollectionUpdateInput): Promise<void>
Updates name, description, tags, or visibility. There is no separate
visibility endpoint - pass isPublic here.
const created = await client.constraints.collections.create({
name: `docs-demo-${Date.now()}`,
description: "original",
isPublic: false,
});
await client.constraints.collections.update(created.id, {
name: `docs-demo-updated-${Date.now()}`,
description: "updated",
tags: ["updated"],
isPublic: true,
});
const detail = await client.constraints.collections.get(created.id);
await client.constraints.collections.delete(created.id);
return {
name: detail.name,
description: detail.description,
tags: detail.tags,
isPublic: detail.isPublic,
};delete
client.constraints.collections.delete(id: string): Promise<void>
const created = await client.constraints.collections.create({ name: `docs-demo-${Date.now()}` });
await client.constraints.collections.delete(created.id);
try {
await client.constraints.collections.get(created.id);
return { deleted: false };
} catch (err) {
if (err instanceof PromptyNotFoundError) return { deleted: true };
throw err;
}vote
client.constraints.collections.vote(id: string, value: 1 | -1): Promise<void>
const created = await client.constraints.collections.create({ name: `docs-demo-vote-${Date.now()}` });
await client.constraints.collections.vote(created.id, 1);
const detail = await client.constraints.collections.get(created.id);
await client.constraints.collections.delete(created.id);
return { upvotes: detail.upvotes, userVote: detail.userVote };unvote
client.constraints.collections.unvote(id: string): Promise<void>
const created = await client.constraints.collections.create({ name: `docs-demo-unvote-${Date.now()}` });
await client.constraints.collections.vote(created.id, -1);
await client.constraints.collections.unvote(created.id);
const detail = await client.constraints.collections.get(created.id);
await client.constraints.collections.delete(created.id);
return { downvotes: detail.downvotes, userVote: detail.userVote };toggleFavorite
client.constraints.collections.toggleFavorite(id: string): Promise<{ favorited: boolean }>
const created = await client.constraints.collections.create({ name: `docs-demo-fav-${Date.now()}` });
const a = await client.constraints.collections.toggleFavorite(created.id);
const b = await client.constraints.collections.toggleFavorite(created.id);
await client.constraints.collections.delete(created.id);
return { firstToggle: a.favorited, secondToggle: b.favorited };listItems
client.constraints.collections.listItems(id: string): Promise<readonly ConstraintCollectionItem[]>
Returns the constraints currently in the collection. Each item carries
the join-row id, the underlying constraintId,
and the constraint text.
const constraint = await client.constraints.create({
text: `docs-demo-c ${Date.now()}`,
isPublic: false,
});
const collection = await client.constraints.collections.create({
name: `docs-demo-coll-${Date.now()}`,
isPublic: false,
itemIds: [constraint.id],
});
const items = await client.constraints.collections.listItems(collection.id);
await client.constraints.collections.delete(collection.id);
await client.constraints.delete(constraint.id);
return items;setItems
client.constraints.collections.setItems(id: string, itemIds: readonly string[]): Promise<void>
Replaces the entire constraint set for the collection - pass an empty
array to clear it. This single method replaces the previous
setConstraints on the legacy flat namespace.
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.constraints.collections.create({ name: `docs-coll-${Date.now()}`, isPublic: false });
await client.constraints.collections.setItems(collection.id, [c1.id]);
const after1 = (await client.constraints.collections.listItems(collection.id)).length;
await client.constraints.collections.setItems(collection.id, [c1.id, c2.id]);
const after2 = (await client.constraints.collections.listItems(collection.id)).length;
await client.constraints.collections.setItems(collection.id, []);
const after3 = (await client.constraints.collections.listItems(collection.id)).length;
await client.constraints.collections.delete(collection.id);
await client.constraints.delete(c1.id);
await client.constraints.delete(c2.id);
return { afterFirstSet: after1, afterSecondSet: after2, afterClear: after3 };