Libraries

Libraries are top-level groups of prompts. A library has its own identity, engagement (votes, favorites, comments), tags, and visibility independent of the prompts it contains. Use libraries to curate collections of prompts for a workflow, an audience, or yourself; share the library publicly while keeping its members' visibility unchanged.

Methods

list
listAll
get
create
update
delete
vote
unvote
toggleFavorite
listPrompts
listAllPrompts
addPrompt
removePrompt

About destructive examples Examples marked writes to your account create real libraries and prompts and clean them up. You'll be prompted to confirm before they run.

list

client.libraries.list(params?: ListParams): Promise<Page<LibrarySummary>>

Paginated list of libraries. Returns a navigable Page<T>.

Parameters

Name	Type	Default	Description
`page`	`number`	`1`	1-based page number.
`pageSize`	`6 \| 12 \| 24 \| 48 \| 100`	`12`	Items per page (server-enforced enum).
`sort`	`"newest" \| "most-upvoted" \| "most-favorited"`	`"newest"`	Sort order.
`scope`	`"public" \| "mine" \| "favorites" \| "all"`	`"public"`	Which libraries to include.
`search`	`string`	-	Full-text search (max 200 chars). Supports `tag:<name>` tokens for tag filtering.
`signal`	`AbortSignal`	-	Abort the request.

const page = await client.libraries.list({
  scope: "public",
  sort: "most-favorited",
  pageSize: 6,
});

return {
  total: page.total,
  page: page.page,
  hasNext: page.hasNext,
  items: page.items.map((l) => ({
    id: l.id,
    name: l.name,
    promptCount: l.promptCount,
    favoritesCount: l.favoritesCount,
  })),
};

listAll

client.libraries.listAll(params?: ListParams): AsyncIterable<LibrarySummary>

Async iterator that walks every page automatically. Use for await; break stops further requests.

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

get

client.libraries.get(id: string): Promise<Library>

Fetch the full Library by id. Throws PromptyNotFoundError on 404.

const page = await client.libraries.list({ scope: "public", pageSize: 6, sort: "most-favorited" });
const first = page.items[0];
if (!first) return { empty: true };

const library = await client.libraries.get(first.id);
return {
  id: library.id,
  name: library.name,
  description: library.description.slice(0, 120) + (library.description.length > 120 ? "…" : ""),
  tags: library.tags,
  isPublic: library.isPublic,
  isOwner: library.isOwner,
  promptCount: library.promptCount,
};

create

client.libraries.create(input: LibraryCreateInput): Promise<LibraryCreateResponse>

Create a new library. The response is narrower than Library - it carries id, name, description, isPublic, and tags. Call get(response.id) if you need the engagement fields and promptCount.

⚠️ Writes to your account. Cleans up after itself.

const created = await client.libraries.create({
  name: "Docs demo: starter library",
  description: "Created from the @prompty-tools/core docs site.",
  isPublic: false,
  tags: ["demo", "docs"],
});
console.log("created", created.id);

await client.libraries.delete(created.id);
console.log("cleaned up", created.id);

return created;

update

client.libraries.update(id: string, input: LibraryUpdateInput): Promise<void>

Update a library in place. name is required even if unchanged - the server enforces a complete payload on PATCH.

⚠️ Writes to your account. Cleans up after itself.

const created = await client.libraries.create({
  name: "Docs demo: original",
  description: "Original description.",
  isPublic: false,
});

await client.libraries.update(created.id, {
  name: "Docs demo: renamed",
  description: "Updated description.",
  isPublic: false,
  tags: ["docs", "renamed"],
});

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

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

return { id: created.id, name: detail.name, description: detail.description, tags: detail.tags };

delete

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

Permanently delete a library. Member prompts are not deleted; only the library record and its membership join rows are removed. Resolves with void.

⚠️ Writes to your account. Cleans up after itself.

const created = await client.libraries.create({
  name: "Docs demo: ephemeral library",
  isPublic: false,
});

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

try {
  await client.libraries.get(created.id);
  return { deleted: false, note: "Still found?" };
} catch (err) {
  if (err instanceof PromptyNotFoundError) {
    return { deleted: true, status: err.status };
  }
  throw err;
}

vote

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

Upvote (1) or downvote (-1) a library.

⚠️ Writes to your account. Cleans up after itself.

const created = await client.libraries.create({
  name: "Docs demo: vote target",
  isPublic: false,
});

await client.libraries.vote(created.id, 1);
const detail = await client.libraries.get(created.id);

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

return { upvotes: detail.upvotes, downvotes: detail.downvotes, userVote: detail.userVote };

unvote

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

Remove the caller's vote (sends { value: null } to the same endpoint). Idempotent - calling it without a prior vote is a no-op.

⚠️ Writes to your account. Cleans up after itself.

const created = await client.libraries.create({
  name: "Docs demo: unvote",
  isPublic: false,
});

await client.libraries.vote(created.id, 1);
const afterVote = await client.libraries.get(created.id);

await client.libraries.unvote(created.id);
const afterUnvote = await client.libraries.get(created.id);

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

return {
  afterVote: { upvotes: afterVote.upvotes, userVote: afterVote.userVote },
  afterUnvote: { upvotes: afterUnvote.upvotes, userVote: afterUnvote.userVote },
};

toggleFavorite

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

Flip the favorite state. The endpoint is a true toggle on the server - there is no set-favorite-to-X form. The response tells you the resulting state.

⚠️ Writes to your account. Cleans up after itself.

const created = await client.libraries.create({
  name: "Docs demo: favorite toggle",
  isPublic: false,
});

const a = await client.libraries.toggleFavorite(created.id);
const b = await client.libraries.toggleFavorite(created.id);

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

return { firstToggle: a.favorited, secondToggle: b.favorited };

listPrompts

client.libraries.listPrompts(id: string, params?: ListParams): Promise<Page<LibraryMemberPrompt>>

Paginated list of the prompts that are members of a library. Accepts the same five query params as the top-level list() (page, pageSize, sort, scope, search).

The returned LibraryMemberPrompt shape is similar to PromptSummary but additionally includes isPublic: members can be either public prompts or your own private prompts.

⚠️ Writes to your account. Cleans up after itself.

const prompt = await client.prompts.create({
  title: "Docs demo: member",
  task: "Member task.",
  compiledPrompt: "Member compiled.",
  isPublic: false,
});

const library = await client.libraries.create({
  name: "Docs demo: members host",
  isPublic: false,
});

await client.libraries.addPrompt(library.id, prompt.id);

const page = await client.libraries.listPrompts(library.id, { pageSize: 12 });

await client.libraries.delete(library.id);
await client.prompts.delete(prompt.id);

return {
  total: page.total,
  members: page.items.map((p) => ({ id: p.id, title: p.title, isPublic: p.isPublic })),
};

listAllPrompts

client.libraries.listAllPrompts(id: string, params?: ListParams): AsyncIterable<LibraryMemberPrompt>

Async iterator over every member prompt in a library. Walks pages automatically; break stops further requests.

const page = await client.libraries.list({ scope: "public", pageSize: 6, sort: "most-favorited" });
const first = page.items[0];
if (!first) return { empty: true };

const titles = [];
for await (const member of client.libraries.listAllPrompts(first.id, { pageSize: 24 })) {
  titles.push(member.title);
  if (titles.length >= 24) break;
}
return { libraryId: first.id, libraryName: first.name, sampleTitles: titles };

addPrompt

client.libraries.addPrompt(id: string, promptId: string): Promise<void>

Add a prompt to a library. The prompt must be either public or owned by the caller; adding the same prompt twice is rejected with a 400.

⚠️ Writes to your account. Cleans up after itself.

const prompt = await client.prompts.create({
  title: "Docs demo: addPrompt",
  task: "Add me.",
  compiledPrompt: "Add me.",
  isPublic: false,
});

const library = await client.libraries.create({
  name: "Docs demo: addPrompt host",
  isPublic: false,
});

await client.libraries.addPrompt(library.id, prompt.id);
const detail = await client.libraries.get(library.id);

await client.libraries.delete(library.id);
await client.prompts.delete(prompt.id);

return { libraryId: library.id, promptCount: detail.promptCount };

removePrompt

client.libraries.removePrompt(id: string, promptId: string): Promise<void>

Remove a prompt from a library. Sends the promptId as a URL query parameter (not a body) - this is the only DELETE in the package that uses a query argument. The server returns 400 if the prompt is not currently a member.

⚠️ Writes to your account. Cleans up after itself.

const prompt = await client.prompts.create({
  title: "Docs demo: removePrompt",
  task: "Remove me.",
  compiledPrompt: "Remove me.",
  isPublic: false,
});

const library = await client.libraries.create({
  name: "Docs demo: removePrompt host",
  isPublic: false,
});

await client.libraries.addPrompt(library.id, prompt.id);
const afterAdd = await client.libraries.get(library.id);

await client.libraries.removePrompt(library.id, prompt.id);
const afterRemove = await client.libraries.get(library.id);

await client.libraries.delete(library.id);
await client.prompts.delete(prompt.id);

return {
  afterAdd: afterAdd.promptCount,
  afterRemove: afterRemove.promptCount,
};