SDK overview

@junjo/sdk is the TypeScript client. Same package runs in Node and the browser; tree-shakeable; zero runtime dependencies beyond fetch (a built-in everywhere we ship to).

Construct a client

import { Junjo } from "@junjo/sdk";
 
const junjo = new Junjo({
  apiKey: process.env.JUNJO_API_KEY!,
  // baseUrl: "https://api.junjo.io", // default
});

Option	Required	Notes
`apiKey`	yes	The full `prefix.secret` string issued in the dashboard or by `npm run db:seed`.
`baseUrl`	no	Override the API root. Trailing slashes are stripped. Defaults to the cloud endpoint.
`authAdapter`	no	An `AuthAdapter` (Clerk, Supabase, JWT, or BYO). Used by the permission-resolution path; not required for server-to-server calls.
`fetch`	no	Override the `fetch` implementation. Useful in environments without a global `fetch`, and to mock requests in tests.

Errors

Every method that talks to the server throws JunjoError for any non-2xx response. The instance preserves the server’s envelope:

import { JunjoError } from "@junjo/sdk";
 
try {
  await junjo.groups.create({ kind: "guild", name: "" });
} catch (e) {
  if (e instanceof JunjoError) {
    e.code;    // "bad_request"
    e.status;  // 400
    e.message; // "name: too short"
  }
}

Branch on error.code, not on error.message. Codes are stable; messages are not.

Sub-namespaces

The Junjo instance exposes typed namespaces for each resource. See the per-namespace pages for the methods inside each.

Namespace	Methods
`junjo.groups`	CRUD, invites, membership lifecycle, group relationships, sub-group `setParent` / `listChildren`, `subscribe` (SSE).
`junjo.roles`	`create`, `get`, `update`, `delete`, `list`, `grantPermission`, `revokePermission`.
`junjo.members`	Read (`get`, `getById`, `list`, `listForUser`), metadata / notes (`setMetadata`, `setNotes`), role assignment (`assignRole`, `removeRole`), permission overrides (`overridePermission`, `clearPermissionOverride`, `listPermissionOverrides`).
`junjo.invitations`	`list`, `get`, `revoke`. Accept and decline live on `junjo.groups` (`acceptInvitation`, `declineInvitation`).
`junjo.audit`	`list`.
`junjo.webhooks`	`verify`, `middleware`; `endpoints.{create,list,update,delete}`.

Top-level methods

In addition to the resource namespaces, Junjo exposes a small set of cross-cutting methods directly on the instance.

Method	Notes
`junjo.can(userId, groupId, permission)`	Boolean wrapper around `check`.
`junjo.check(userId, groupId, permission)`	Returns the full `PermissionCheckResult`.
`junjo.whoami(token)`	Delegates to the configured `authAdapter.verifyToken`; returns `{ userId } \| null`. Throws `JunjoError({ code: "invalid_config" })` if no `authAdapter` was passed to the constructor.

Self-hosting groups