@stanza-client/sdk
v0.1.2
Published
Official JavaScript SDK for the Stanza public REST API (/api/v1). Framework-agnostic core on native fetch plus an optional thin React layer.
Readme
@stanza-client/sdk
Official JavaScript SDK for the Stanza public REST API (/api/v1).
Framework-agnostic core on native fetch — works in Node 20+, browsers and
edge runtimes — plus an optional thin React layer (@stanza-client/sdk/react).
Install
npm i @stanza-client/sdkCreate an API key in the dashboard: Developers → API keys
(stz_…, pick scopes like roadmap:read roadmap:write).
Quickstart
import { StanzaClient } from "@stanza-client/sdk";
const stanza = new StanzaClient({
apiKey: process.env.STANZA_KEY!,
baseUrl: "https://your-host",
});
// List cards
const page = await stanza.roadmap.list({ limit: 20 });
// Create a card (safe to retry: same idempotencyKey = one card)
const card = await stanza.roadmap.create(
{ title: "From my agent", status: "planned", priority: "high" },
{ idempotencyKey: "agent-job-123" },
);
// Move it to In Progress, top of column
await stanza.roadmap.move(card.id, { status: "in_progress", index: 0 });
// Comment
await stanza.roadmap.comments.add(card.id, { text: "Picked up by agent-7" });Changelog updates:
const drafts = await stanza.updates.list({ status: "draft" });
const post = await stanza.updates.create({ title: "v2.4 is live", content: "What is new..." });
await stanza.updates.setStatus(post.id, "published");Resources
stanza.roadmap—list,listAll(auto-pagination),get,create,update,remove,move,archive,upvote,comments.{list,add,remove},activitystanza.tags—list,create,update,remove,mergestanza.bugs—list,listAll,setStatus,convertstanza.updates—list,listAll,get,create,update,setStatus,removestanza.members—list(resolve emails toassigneeId)stanza.webhooks—list,create,update,remove,test
Rules of the road
- Auth:
Authorization: Bearer stz_…is sent on every request. - Errors: every non-2xx response throws
StanzaErrorwith{ status, code, message }(server shape:{ error: { code, message } }). - Rate limit: 600 req/min per key — the SDK retries 429/5xx with
exponential backoff (configurable via
maxRetries: 0to disable). - Idempotency: pass
{ idempotencyKey }on create/move — replays return the original response. - Pagination:
listreturns{ data, pagination: { nextCursor, total } };listAllfollowsnextCursorfor you.
React
import { StanzaClient } from "@stanza-client/sdk";
import { useStanzaMutation, useStanzaQuery } from "@stanza-client/sdk/react";
const stanza = new StanzaClient({ apiKey, baseUrl });
function Board() {
const cards = useStanzaQuery(stanza, "cards", (c) => c.roadmap.list({ limit: 20 }));
const create = useStanzaMutation(stanza, (c, title: string) => c.roadmap.create({ title }));
// cards: { data, error, loading, refetch }
// create: { data, error, loading, mutate }
}Live smoke test (opt-in)
STANZA_URL="https://your-host" STANZA_KEY="stz_…" pnpm --filter @stanza-client/sdk test:liveExercises lists, card create/move/comment/delete and draft publish/delete against a real host, then cleans everything up. Skipped when env is missing.
