@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAQ,OAAO,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;GASG;AAEH,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO;gBADhB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO;IAM3B,IAAI,IAAI,IAAI,MAAM,CAEjB;IACD,IAAI,cAAc,IAAI,OAAO,CAE5B;IACD,IAAI,UAAU,IAAI,OAAO,CAExB;IACD,IAAI,QAAQ,IAAI,OAAO,CAEtB;IACD,IAAI,WAAW,IAAI,OAAO,CAEzB;IACD,0GAA0G;IAC1G,IAAI,iBAAiB,IAAI,OAAO,CAE/B;CACF;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,GAAG,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,IAAI,CAAC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;IACrE,mFAAmF;IACnF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,CAAC,CAAC;IACR,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC,2FAA2F;IAC3F,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAcD,qBAAa,kBAAkB;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAe;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,IAAI,EAAE,yBAAyB;IAa3C,0DAA0D;IAC1D,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,kBAAkB;IAIvD,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,MAAM;IAMjD,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IA2BnG,4CAA4C;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,KAAK,CAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,WAAW,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAanK,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IAGhG,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IAGnF,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IAGlF,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IAGpF,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrE,wDAAwD;IAClD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,WAAW,CAAC,OAAO,CAAM,EAAE,KAAK,SAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;CAUxF;AAED,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAI/C"}

package/dist/client.js

@@ -0,0 +1,165 @@
+import { SESSION_HEADER } from "./session.js";
+/**
+ * The Interface API as a Frontend consumes it (components/05-interface-api.md
+ * §Conventions): `X-Asturiu-Session` on every call except session exchange,
+ * `Idempotency-Key` on writes, `If-Match` for concurrency, cursors for
+ * collections, `application/problem+json` for errors — and a `404` that never
+ * distinguishes absent from forbidden.
+ *
+ * Runs wherever `fetch` exists: a Next.js server, an edge runtime, a browser
+ * talking to the Web UI's own `/api/v0` proxy.
+ */
+export class InterfaceApiError extends Error {
+    status;
+    problem;
+    constructor(status, problem) {
+        super(problem.detail ?? problem.title ?? `HTTP ${status}`);
+        this.status = status;
+        this.problem = problem;
+        this.name = "InterfaceApiError";
+    }
+    get type() {
+        return this.problem.type ?? "";
+    }
+    get isUnauthorized() {
+        return this.status === 401;
+    }
+    get isNotFound() {
+        return this.status === 404;
+    }
+    get isPaused() {
+        return this.status === 503 && this.type.endsWith("platform-paused");
+    }
+    get isSuspended() {
+        return this.status === 403 && this.type.endsWith("account-suspended");
+    }
+    /** `POST /v0/sessions` for someone with no Customer yet, while the Tenant takes no new ones (ADR-044). */
+    get isEnrolmentClosed() {
+        return this.status === 403 && this.type.endsWith("enrolment-closed");
+    }
+}
+/** The ambient `fetch`, invoked on the global so it is valid as a method of any object. */
+const globalFetch = (input, init) => globalThis.fetch(input, init);
+function safeJson(text) {
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+export class InterfaceApiClient {
+    baseUrl;
+    prefix;
+    session;
+    ambientSession;
+    f;
+    timeoutMs;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.prefix = opts.prefix ?? "/v0";
+        this.session = opts.session ?? null;
+        this.ambientSession = opts.ambientSession ?? false;
+        // Never store the bare global `fetch` and call it as `this.f(...)`: browsers
+        // then see `this === InterfaceApiClient` and throw
+        // "Failed to execute 'fetch' on 'Window': Illegal invocation" (Node is
+        // lenient, so only the Web UI breaks). Always call through `globalFetch`.
+        this.f = opts.fetch ?? globalFetch;
+        this.timeoutMs = opts.timeoutMs ?? 30000;
+    }
+    /** The same client acting for another (or no) session. */
+    withSession(session) {
+        return new InterfaceApiClient({ baseUrl: this.baseUrl, prefix: this.prefix, session, ambientSession: this.ambientSession, fetch: this.f, timeoutMs: this.timeoutMs });
+    }
+    url(path, query) {
+        const u = new URL(`${this.baseUrl}${this.prefix}${path.startsWith("/") ? path : `/${path}`}`);
+        for (const [k, v] of Object.entries(query ?? {}))
+            if (v !== undefined && v !== null && v !== "")
+                u.searchParams.set(k, String(v));
+        return u.toString();
+    }
+    async call(method, path, opts = {}) {
+        const headers = { accept: "application/json, application/problem+json, */*" };
+        for (const [k, v] of Object.entries(opts.headers ?? {}))
+            if (v !== undefined)
+                headers[k.toLowerCase()] = v;
+        if (opts.session !== false && !this.ambientSession) {
+            if (!this.session)
+                throw new InterfaceApiError(401, { type: "urn:asturiu:problem:unauthorized", title: "Unauthorized", status: 401, detail: "no session" });
+            headers[SESSION_HEADER] = this.session;
+        }
+        let body;
+        if (opts.raw !== undefined) {
+            body = opts.raw;
+            headers["content-type"] = opts.contentType ?? "application/octet-stream";
+        }
+        else if (opts.body !== undefined) {
+            headers["content-type"] = "application/json";
+            body = JSON.stringify(opts.body);
+        }
+        if (["POST", "PUT"].includes(method) && opts.idempotencyKey !== false && !headers["idempotency-key"])
+            headers["idempotency-key"] = opts.idempotencyKey ?? crypto.randomUUID();
+        if (opts.ifMatch !== undefined)
+            headers["if-match"] = String(opts.ifMatch);
+        const res = await this.f(this.url(path, opts.query), { method, headers, body, signal: opts.signal ?? AbortSignal.timeout(this.timeoutMs), cache: "no-store" });
+        const text = await res.text();
+        const json = safeJson(text);
+        if (!res.ok) {
+            const problem = json && typeof json === "object" && "status" in json ? json : { type: "urn:asturiu:problem:http", title: res.statusText || "Error", status: res.status, detail: typeof json === "object" && json && "raw" in json ? String(json.raw).slice(0, 300) : undefined };
+            throw new InterfaceApiError(res.status, problem);
+        }
+        return { status: res.status, body: json, headers: res.headers };
+    }
+    /** Binary download (Attachment content). */
+    async download(path, opts = {}) {
+        const headers = {};
+        if (opts.session !== false && !this.ambientSession) {
+            if (!this.session)
+                throw new InterfaceApiError(401, { type: "urn:asturiu:problem:unauthorized", title: "Unauthorized", status: 401 });
+            headers[SESSION_HEADER] = this.session;
+        }
+        const res = await this.f(this.url(path, opts.query), { method: "GET", headers, signal: opts.signal ?? AbortSignal.timeout(this.timeoutMs), cache: "no-store" });
+        if (!res.ok)
+            throw new InterfaceApiError(res.status, safeJson(await res.text()) ?? { type: "urn:asturiu:problem:http", title: "Error", status: res.status });
+        const cd = res.headers.get("content-disposition") ?? "";
+        const m = /filename="?([^";]+)"?/.exec(cd);
+        return { status: res.status, bytes: await res.arrayBuffer(), contentType: res.headers.get("content-type") ?? "application/octet-stream", filename: m?.[1] };
+    }
+    get(path, query, opts = {}) {
+        return this.call("GET", path, { ...opts, query }).then((r) => r.body);
+    }
+    post(path, body, opts = {}) {
+        return this.call("POST", path, { ...opts, body }).then((r) => r.body);
+    }
+    put(path, body, opts = {}) {
+        return this.call("PUT", path, { ...opts, body }).then((r) => r.body);
+    }
+    patch(path, body, opts = {}) {
+        return this.call("PATCH", path, { ...opts, body }).then((r) => r.body);
+    }
+    delete(path, opts = {}) {
+        return this.call("DELETE", path, opts).then((r) => r.body);
+    }
+    /** Walk every page of a cursor-paginated collection. */
+    async all(path, query = {}, limit = 100) {
+        const out = [];
+        let cursor = null;
+        do {
+            const page = await this.get(path, { ...query, limit, cursor: cursor ?? undefined });
+            out.push(...page.items);
+            cursor = page.next_cursor;
+        } while (cursor);
+        return out;
+    }
+}
+/** Every caller-facing error becomes a problem shape, so UIs render one thing. */
+export function toProblem(err) {
+    if (err instanceof InterfaceApiError)
+        return err.problem;
+    if (err instanceof Error)
+        return { type: "urn:asturiu:problem:client", title: err.name, status: 0, detail: err.message };
+    return { type: "urn:asturiu:problem:client", title: "Error", status: 0, detail: String(err) };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/contacts.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Contacts, handles and disclosure (ADR-024). Pure vocabulary shared by the
+ * Engine, the CLI and every frontend: the pair-state function is the one
+ * place the two rows of a Contact are read into one answer, so it must be the
+ * same everywhere. Dependency-free on purpose.
+ */
+/** A holder's own decision about one Contact, stored on its row. */
+export declare const CONTACT_INTENTS: readonly ["accepted", "incoming", "blocked"];
+export type ContactIntent = (typeof CONTACT_INTENTS)[number];
+/** What one side sees, derived from both rows and never stored. */
+export declare const CONTACT_STATES: readonly ["active", "pending", "incoming", "blocked", "removed"];
+export type ContactState = (typeof CONTACT_STATES)[number];
+/** How the Contact came to exist. */
+export declare const CONTACT_ORIGINS: readonly ["request", "grant", "transfer", "recovery"];
+export type ContactOrigin = (typeof CONTACT_ORIGINS)[number];
+/** The profile fields a holder may disclose to one Contact. The handle is always visible to an active Contact and is not on this list. */
+export declare const DISCLOSABLE_FIELDS: readonly ["display_name", "name", "email", "phone"];
+export type DisclosableField = (typeof DISCLOSABLE_FIELDS)[number];
+/**
+ * The counterpart row as the holder's side sees it: an intent when the row
+ * is readable, `missing` when no counterpart row was ever linked (an external
+ * Principal not redeemed yet), `removed` when the linked row is gone (the
+ * counterpart deleted the Contact, or the Customer was deleted).
+ */
+export type CounterpartIntent = ContactIntent | "missing" | "removed";
+/**
+ * The state one holder sees. Order matters:
+ *
+ * - my own block is always shown to me as `blocked`;
+ * - a counterpart that is gone is `removed`, whatever I had decided;
+ * - a request I have not answered is `incoming`;
+ * - both accepted is `active`;
+ * - everything else — the counterpart has not answered, has declined
+ *   silently, or has blocked me — reads `pending`. A block is never visible
+ *   to the blocked side.
+ */
+export declare function contactState(mine: ContactIntent, theirs: CounterpartIntent): ContactState;
+/** Platform-wide handle (ADR-024): lowercase, 3–30 characters, starts with a letter or digit. */
+export declare const HANDLE_PATTERN: RegExp;
+export declare function isHandle(value: unknown): value is string;
+/** Normalise what a person typed as a handle: trim, lower-case, strip a leading `@`. Validation is `isHandle`. */
+export declare function normalizeHandle(value: string): string;
+//# sourceMappingURL=contacts.d.ts.map

package/dist/contacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contacts.d.ts","sourceRoot":"","sources":["../src/contacts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oEAAoE;AACpE,eAAO,MAAM,eAAe,8CAA+C,CAAC;AAC5E,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,mEAAmE;AACnE,eAAO,MAAM,cAAc,kEAAmE,CAAC;AAC/F,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,qCAAqC;AACrC,eAAO,MAAM,eAAe,uDAAwD,CAAC;AACrF,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,0IAA0I;AAC1I,eAAO,MAAM,kBAAkB,qDAAsD,CAAC;AACtF,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,iBAAiB,GAAG,YAAY,CAMzF;AAED,iGAAiG;AACjG,eAAO,MAAM,cAAc,QAAgC,CAAC;AAE5D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED,kHAAkH;AAClH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/contacts.js

@@ -0,0 +1,46 @@
+/**
+ * Contacts, handles and disclosure (ADR-024). Pure vocabulary shared by the
+ * Engine, the CLI and every frontend: the pair-state function is the one
+ * place the two rows of a Contact are read into one answer, so it must be the
+ * same everywhere. Dependency-free on purpose.
+ */
+/** A holder's own decision about one Contact, stored on its row. */
+export const CONTACT_INTENTS = ["accepted", "incoming", "blocked"];
+/** What one side sees, derived from both rows and never stored. */
+export const CONTACT_STATES = ["active", "pending", "incoming", "blocked", "removed"];
+/** How the Contact came to exist. */
+export const CONTACT_ORIGINS = ["request", "grant", "transfer", "recovery"];
+/** The profile fields a holder may disclose to one Contact. The handle is always visible to an active Contact and is not on this list. */
+export const DISCLOSABLE_FIELDS = ["display_name", "name", "email", "phone"];
+/**
+ * The state one holder sees. Order matters:
+ *
+ * - my own block is always shown to me as `blocked`;
+ * - a counterpart that is gone is `removed`, whatever I had decided;
+ * - a request I have not answered is `incoming`;
+ * - both accepted is `active`;
+ * - everything else — the counterpart has not answered, has declined
+ *   silently, or has blocked me — reads `pending`. A block is never visible
+ *   to the blocked side.
+ */
+export function contactState(mine, theirs) {
+    if (mine === "blocked")
+        return "blocked";
+    if (theirs === "removed")
+        return "removed";
+    if (mine === "incoming")
+        return "incoming";
+    if (theirs === "accepted")
+        return "active";
+    return "pending";
+}
+/** Platform-wide handle (ADR-024): lowercase, 3–30 characters, starts with a letter or digit. */
+export const HANDLE_PATTERN = /^[a-z0-9][a-z0-9._-]{2,29}$/;
+export function isHandle(value) {
+    return typeof value === "string" && HANDLE_PATTERN.test(value);
+}
+/** Normalise what a person typed as a handle: trim, lower-case, strip a leading `@`. Validation is `isHandle`. */
+export function normalizeHandle(value) {
+    return value.trim().replace(/^@/, "").toLowerCase();
+}
+//# sourceMappingURL=contacts.js.map

package/dist/contacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contacts.js","sourceRoot":"","sources":["../src/contacts.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,CAAU,CAAC;AAG5E,mEAAmE;AACnE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,CAAU,CAAC;AAG/F,qCAAqC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAU,CAAC;AAGrF,0IAA0I;AAC1I,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAWtF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,IAAmB,EAAE,MAAyB;IACzE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,IAAI,KAAK,UAAU;QAAE,OAAO,UAAU,CAAC;IAC3C,IAAI,MAAM,KAAK,UAAU;QAAE,OAAO,QAAQ,CAAC;IAC3C,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,iGAAiG;AACjG,MAAM,CAAC,MAAM,cAAc,GAAG,6BAA6B,CAAC;AAE5D,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC;AAED,kHAAkH;AAClH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AACtD,CAAC"}