@spendgraph/sdk 0.4.0 → 0.5.1

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { Client } from "./core/client/index.js";
 import type { ClientOptions } from "./core/types.js";
-import { Alerts, Credentials, Events, Ingest, Invites, Keys, Models, Playground, Pricing, Projects, Prompts, PromptsAdmin, Stats, Tools } from "./resources/index.js";
+import { Alerts, Cli, Credentials, Events, Ingest, Invites, Keys, Models, Playground, Pricing, Projects, Prompts, PromptsAdmin, Stats, Tools } from "./resources/index.js";
 export interface SpendgraphOptions extends ClientOptions {
     /** Scopes writes that accept one. A key is already pinned to its project. */
     project?: string;
@@ -13,12 +13,14 @@ export interface SpendgraphOptions extends ClientOptions {
  *
  * An `apiKey` reaches usage, stats and prompts. The dashboard half — keys,
  * projects, pricing, credentials — is gated on a signed-in user server-side and
- * needs `session`; there is no API-key path to it, which is what stops a leaked
- * ingest key from minting more keys or reading a provider secret.
+ * needs `session` or an `sgc_` `token`; there is no API-key path to it, which is
+ * what stops a leaked ingest key from minting more keys or reading a provider
+ * secret. `cli` is how a terminal obtains a token, and how you revoke one.
  */
 export declare class Spendgraph {
     /** The transport. Reach for it only for a route this class does not cover. */
     readonly http: Client;
+    readonly cli: Cli;
     readonly ingest: Ingest;
     readonly stats: Stats;
     readonly events: Events;

package/dist/client.js

@@ -1,7 +1,8 @@
 import { Client } from "./core/client/index.js";
-import { Alerts, Credentials, Events, Ingest, Invites, Keys, Models, Playground, Pricing, Projects, Prompts, PromptsAdmin, Stats, Tools, } from "./resources/index.js";
+import { Alerts, Cli, Credentials, Events, Ingest, Invites, Keys, Models, Playground, Pricing, Projects, Prompts, PromptsAdmin, Stats, Tools, } from "./resources/index.js";
 export class Spendgraph {
     http;
+    cli;
     ingest;
     stats;
     events;
@@ -18,6 +19,7 @@ export class Spendgraph {
     tools;
     constructor(opts) {
         this.http = new Client(opts);
+        this.cli = new Cli(this.http);
         this.ingest = new Ingest(this.http, opts.project);
         this.stats = new Stats(this.http);
         this.events = new Events(this.http);

package/dist/core/client/client.d.ts

@@ -17,12 +17,22 @@ export declare class Client {
     constructor(opts: ClientOptions);
     /** True once anything is set that the server might accept. */
     get authenticated(): boolean;
-    request<T>(path: string, init?: RequestInit): Promise<T>;
+    request<T>(path: string, init?: RequestInit, opts?: {
+        anonymous?: boolean;
+    }): Promise<T>;
     get<T>(path: string, query?: Query): Promise<T>;
     post<T>(path: string, body?: unknown, query?: Query): Promise<T>;
     put<T>(path: string, body?: unknown, query?: Query): Promise<T>;
     patch<T>(path: string, body?: unknown, query?: Query): Promise<T>;
     delete<T>(path: string, query?: Query): Promise<T>;
+    /**
+     * A POST that deliberately carries no credential.
+     *
+     * Only for the two calls that exist to obtain one. Everything else goes
+     * through `post`, so "this request was unauthenticated" stays a decision
+     * written at the call site rather than a side effect of having nothing set.
+     */
+    postAnonymous<T>(path: string, body?: unknown): Promise<T>;
     private send;
     /** A 204 and an empty body are success, not a JSON parse failure. */
     private decode;

package/dist/core/client/client.js

@@ -36,14 +36,15 @@ export class Client {
             ...opts.headers,
             ...(opts.apiKey ? { "x-api-key": opts.apiKey } : {}),
             ...(opts.session ? { cookie: opts.session } : {}),
+            ...(opts.token ? { authorization: `Bearer ${opts.token}` } : {}),
         };
     }
     get authenticated() {
         return Object.keys(this.auth).length > 0;
     }
-    async request(path, init = {}) {
-        if (!this.authenticated) {
-            throw new SpendgraphError(401, "no_credentials", "No spendgraph apiKey or session set.");
+    async request(path, init = {}, opts = {}) {
+        if (!opts.anonymous && !this.authenticated) {
+            throw new SpendgraphError(401, "no_credentials", "No spendgraph apiKey, session or token set.");
         }
         const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
         let last;
@@ -90,6 +91,9 @@ export class Client {
     delete(path, query) {
         return this.request(`${path}${queryString(query)}`, { method: "DELETE" });
     }
+    postAnonymous(path, body) {
+        return this.request(path, { method: "POST", ...(body === undefined ? {} : { body: JSON.stringify(body) }) }, { anonymous: true });
+    }
     send(method, path, body, query) {
         return this.request(`${path}${queryString(query)}`, {
             method,

package/dist/core/types.d.ts

@@ -9,6 +9,12 @@ export interface Credentials {
      * server rather than a different answer from here.
      */
     session?: string;
+    /**
+     * An `sgc_` terminal token, from `cli.exchange` after somebody approved it in
+     * a browser. It stands in for that person's session everywhere a session is
+     * accepted, and unlike one it can be revoked — see `cli.revoke`.
+     */
+    token?: string;
     /** Sent on every request, under anything set above. */
     headers?: Record<string, string>;
 }

package/dist/resources/cli.d.ts

@@ -0,0 +1,60 @@
+import type { Client } from "../core/client/index.js";
+export interface TerminalRow {
+    id: string;
+    label: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+    expiresAt: string;
+}
+export interface DeviceAuth {
+    /** The secret the terminal keeps. Never put it in a URL or show it to anyone. */
+    deviceCode: string;
+    /** The code in the link, formatted for a person to compare against. */
+    userCode: string;
+    /** Path to open in a browser, joined to your base URL. */
+    verifyPath: string;
+    expiresAt: string;
+}
+export interface Terminal {
+    token: string;
+    label: string;
+    expiresAt: string;
+}
+/**
+ * Signing a terminal in, and signing one out.
+ *
+ * `start` and `exchange` are the only two calls in this SDK that send no
+ * credential: they are how one is obtained. The pair of secrets in `exchange`
+ * is the claim being made — the device code proves it is the same terminal that
+ * asked, and the one-time code proves a person approved it in a browser.
+ */
+export declare class Cli {
+    private readonly client;
+    constructor(client: Client);
+    /** Opens a request. `label` is what the approval page shows the person. */
+    start(body: {
+        label: string;
+    }): Promise<DeviceAuth>;
+    /** Redeems an approved request. One token per approval, then the request is spent. */
+    exchange(body: {
+        deviceCode: string;
+        otp: string;
+    }): Promise<Terminal>;
+    /** Every terminal signed in as you. */
+    terminals(): Promise<{
+        terminals: TerminalRow[];
+    }>;
+    /** Signs one out by id. Yours only — somebody else's answers 404. */
+    revoke(id: string): Promise<{
+        revoked: {
+            id: string;
+        };
+    }>;
+    /** Signs out the terminal making this call, which is the one that knows its own token. */
+    revokeSelf(): Promise<{
+        revoked: {
+            id: string;
+        };
+    }>;
+}

package/dist/resources/cli.js

@@ -0,0 +1,21 @@
+export class Cli {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    start(body) {
+        return this.client.postAnonymous("/api/v1/cli/auth", body);
+    }
+    exchange(body) {
+        return this.client.postAnonymous("/api/v1/cli/token", body);
+    }
+    terminals() {
+        return this.client.get("/api/v1/cli/tokens");
+    }
+    revoke(id) {
+        return this.client.delete(`/api/v1/cli/tokens/${encodeURIComponent(id)}`);
+    }
+    revokeSelf() {
+        return this.client.delete("/api/v1/cli/tokens/current");
+    }
+}

package/dist/resources/index.d.ts

@@ -1,5 +1,7 @@
 export type { AlertRow } from "./alerts.js";
 export { Alerts } from "./alerts.js";
+export type { DeviceAuth, Terminal, TerminalRow } from "./cli.js";
+export { Cli } from "./cli.js";
 export { Credentials } from "./credentials.js";
 export type { EventsPage, EventsQuery, UsageEventRow } from "./events.js";
 export { Events } from "./events.js";

package/dist/resources/index.js

@@ -1,4 +1,5 @@
 export { Alerts } from "./alerts.js";
+export { Cli } from "./cli.js";
 export { Credentials } from "./credentials.js";
 export { Events } from "./events.js";
 export { Ingest, MAX_EVENTS } from "./ingest.js";

package/dist/resources/projects.d.ts

@@ -33,9 +33,23 @@ export declare class Projects {
     removeMember(projectId: string, userId: string): Promise<{
         ok: boolean;
     }>;
-    invite(projectId: string, body: Record<string, unknown>): Promise<{
-        ok: boolean;
-        added?: unknown;
+    /**
+     * Invites by GitHub login, or mints a shareable link when none is given.
+     *
+     * Typed rather than `Record<string, unknown>`: the route reads `githubLogin`
+     * and nothing else, so an untyped body let a caller send `email`, have it
+     * silently dropped, and get a link invite it never asked for under a 200.
+     */
+    invite(projectId: string, body: {
+        githubLogin?: string;
+        role?: "owner" | "member";
+    }): Promise<{
+        added: boolean;
+        githubLogin: string | null;
+        role: "owner" | "member";
+        expiresAt?: string;
+        /** Present only for a link invite, and only this once. */
+        token?: string | null;
     }>;
     revokeInvite(projectId: string, inviteId: string): Promise<{
         ok: boolean;

package/dist/resources/prompts.d.ts

@@ -68,7 +68,7 @@ export declare class Prompts {
     list(query?: Scoped & {
         limit?: number;
         cursor?: string;
-        archived?: boolean;
+        archived?: "only" | "active" | "all";
     }): Promise<{
         prompts: unknown[];
         nextCursor?: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/sdk",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Track LLM input/output tokens and cost. Three functions, zero dependencies, fail-open.",
   "license": "MIT",
   "repository": {