Tones

Tones are short labels (e.g. "playful", "formal") that prompts and collections reference. Tones are non-versioned and the server enforces label uniqueness per user. There's no dedicated visibility endpoint - pass isPublic through update() instead.

Methods

list

client.tones.list(params?: ListParams): Promise<Page<ToneSummary>>

List public tones 
const page = await client.tones.list({ scope: "public", pageSize: 12, sort: "most-upvoted" });
return {
  total: page.total,
  items: page.items.map((t) => ({ id: t.id, label: t.label, tags: t.tags })),
};

listAll

client.tones.listAll(params?: ListParams): AsyncIterable<ToneSummary>

Iterate the public tones feed 
const labels = [];
for await (const tone of client.tones.listAll({ scope: "public", pageSize: 12 })) {
  labels.push(tone.label);
  if (labels.length >= 12) break;
}
return labels;

get

client.tones.get(id: string): Promise<Tone>

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

const tone = await client.tones.get(first.id);
return {
  id: tone.id,
  label: tone.label,
  tags: tone.tags,
  isPublic: tone.isPublic,
  upvotes: tone.upvotes,
  isOwner: tone.isOwner,
};

create

client.tones.create(input: ToneCreateInput): Promise<ToneCreateResponse>

Tone labels must be unique per user. The server returns 400 with "A tone with this label already exists" on collision.

⚠️ Writes to your account. Cleans up after itself.
Create then delete (with unique label) 
// Use a timestamp to avoid collisions on repeat runs.
const label = `docs-demo-tone-${Date.now()}`;
const created = await client.tones.create({ label, isPublic: false, tags: ["demo"] });
console.log("created", created);
await client.tones.delete(created.id);
return created;

update

client.tones.update(id: string, input: ToneUpdateInput): Promise<void>

Updates the label, tags, or visibility. Tones don't have versions - the server overwrites the row directly.

⚠️ Writes to your account. Cleans up after itself.
Create, update label + visibility, clean up 
const created = await client.tones.create({
  label: `docs-demo-tone-${Date.now()}`,
  isPublic: false,
});

await client.tones.update(created.id, {
  label: `docs-demo-tone-updated-${Date.now()}`,
  tags: ["docs", "updated"],
  isPublic: true,
});

const detail = await client.tones.get(created.id);

await client.tones.delete(created.id);

return { label: detail.label, tags: detail.tags, isPublic: detail.isPublic };

delete

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

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

vote

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

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

unvote

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

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

toggleFavorite

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

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