@cosmoops/connect-sdk 0.1.0

package/dist/cjs/server/resources/ai.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiResource = void 0;
+const http_js_1 = require("../http.js");
+/** RAG chat and structured extraction against an organization's data. */
+class AiResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * RAG-grounded chat. Returns the raw streaming `Response` rather than a
+     * parsed body - this endpoint answers with server-sent events, and buffering
+     * it here would throw away the only reason to stream. Pipe
+     * `response.body` onward, or hand it to the AI SDK's own reader.
+     */
+    chat(input, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/ai/chat",
+            json: input,
+            raw: true,
+            signal: options.signal,
+        });
+    }
+    /** Extract structured JSON from a file or image URL, against a platform extraction schema referenced by id. */
+    async extract(input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/ai/extract",
+            json: input,
+        });
+        return result.data;
+    }
+}
+exports.AiResource = AiResource;

package/dist/cjs/server/resources/apps.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppsResource = void 0;
+const http_js_1 = require("../http.js");
+/** The services an organization can open - the data behind a launcher grid. */
+class AppsResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Launchable apps only, so a grid tile is never a dead end. The calling
+     * service is included and flagged `isCurrent` rather than filtered out.
+     */
+    async list(organizationId) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/apps",
+            query: { organizationId },
+        });
+        // `?? []` for the same reason `billing.listPlans` has it: this is a
+        // collection every caller immediately maps or measures, and a body without
+        // the key would hand them `undefined`. Worse, the bridge re-wraps this as
+        // `{ apps: <value> }` and `JSON.stringify` drops an `undefined` member
+        // entirely - so one missing key upstream reaches the browser as `{}` and
+        // crashes on `.length`, past every `response.ok` check in between.
+        return result.apps ?? [];
+    }
+}
+exports.AppsResource = AppsResource;

package/dist/cjs/server/resources/billing.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BillingResource = void 0;
+const http_js_1 = require("../http.js");
+const helpers_js_1 = require("../../helpers.js");
+/** The plan catalog you sell, and metering usage back against a subscriber's add-on balance. */
+class BillingResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Your service's active plans - render live pricing instead of hardcoding it.
+     *
+     * `features` is normalised on the way out: Connect used to send bare keys
+     * and now sends `{ key, name, description }`, and this SDK is versioned
+     * independently of the instance it talks to. Without the coercion a partner
+     * pointed at a Connect that has not upgraded yet renders a feature list of
+     * blanks - which is exactly what happened. See `normalizePlanFeatures`.
+     */
+    async listPlans() {
+        const response = await (0, http_js_1.request)(this.transport, { method: "GET", path: "/plans" });
+        return {
+            plans: (response.plans ?? []).map((plan) => ({
+                ...plan,
+                features: (0, helpers_js_1.normalizePlanFeatures)(plan.features),
+            })),
+        };
+    }
+    /**
+     * What is left of every consumable add-on on an organization's
+     * subscription - the read half of `consumeAddon`.
+     *
+     * Needs a key scoped to `addons:read`, which is separate from
+     * `addons:consume` on purpose: a key that only renders a usage meter should
+     * not also be able to spend the balance down.
+     *
+     * Returns an empty `addons` array rather than throwing when there is
+     * nothing to meter, so a caller can render it unconditionally.
+     */
+    async getAddonUsage(organizationId) {
+        const response = await (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: `/addons/organizations/${(0, http_js_1.pathSegment)(organizationId, "organizationId")}`,
+        });
+        // Normalised, not passed through: the promise above resolves for any 2xx,
+        // and `ConnectUsageMeter` reads `addons` straight off it. A body without
+        // the key is not an error the meter can see - `data` is truthy, so its
+        // `!data` guard passes - and it crashes on `.length` instead of doing what
+        // it promises for an empty list, which is to render nothing.
+        return { ...response, addons: response.addons ?? [], resetsAt: response.resetsAt ?? null };
+    }
+    /**
+     * Debit a consumable add-on's per-cycle balance on behalf of an
+     * organization's users. Call it at whatever cadence your usage happens.
+     *
+     * An `Idempotency-Key` is always sent, generated per call when you do not
+     * supply one: a balance cannot be un-spent, so a retried consume without a
+     * key double-debits. Pass your own when the natural unit of work is
+     * something you can name (a job id, a message id) and might submit twice.
+     */
+    consumeAddon(input, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/addons/consume",
+            json: input,
+            headers: { "idempotency-key": options.idempotencyKey ?? crypto.randomUUID() },
+        });
+    }
+}
+exports.BillingResource = BillingResource;

package/dist/cjs/server/resources/drive.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriveResource = void 0;
+const http_js_1 = require("../http.js");
+/** Files in an organization's Drive - upload, and signed URLs to read back. */
+class DriveResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    upload(input) {
+        const form = new FormData();
+        const fileName = input.fileName ?? input.file.name ?? "upload";
+        form.set("file", input.file, fileName);
+        form.set("organizationId", input.organizationId);
+        if (input.parentId)
+            form.set("parentId", input.parentId);
+        return (0, http_js_1.request)(this.transport, { method: "POST", path: "/drive/files", multipart: form });
+    }
+    /** A signed URL for the original bytes. Short-lived - fetch it when you need it, do not store it. */
+    async getFileUrl(fileId, input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: `/drive/files/${(0, http_js_1.pathSegment)(fileId, "fileId")}/url`,
+            query: { organizationId: input.organizationId },
+        });
+        return result.url;
+    }
+    /** A signed URL for the thumbnail. Same lifetime caveat as `getFileUrl`. */
+    async getPreviewUrl(fileId, input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: `/drive/files/${(0, http_js_1.pathSegment)(fileId, "fileId")}/preview-url`,
+            query: { organizationId: input.organizationId, size: input.size },
+        });
+        return result.url;
+    }
+}
+exports.DriveResource = DriveResource;

package/dist/cjs/server/resources/entitlements.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntitlementsResource = void 0;
+const http_js_1 = require("../http.js");
+/**
+ * The two checks worth making on every request: may this workspace be here at
+ * all, and what is it paying for.
+ */
+class EntitlementsResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Every gate Connect owns between an organization and your service -
+     * subscription, KYC/KYB, a chargeable payment method, seat headroom -
+     * resolved in one call.
+     *
+     * Blocked users are the point: each blocker carries a `resolveUrl` into the
+     * Connect screen that fixes it, so you can route them somewhere useful
+     * instead of refusing them with nowhere to go.
+     */
+    getReadiness(organizationId) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: `/onboarding/organizations/${(0, http_js_1.pathSegment)(organizationId, "organizationId")}`,
+        });
+    }
+    /** The live plan and subscription, including `plan.features`. */
+    getSubscription(organizationId) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: `/subscriptions/organizations/${(0, http_js_1.pathSegment)(organizationId, "organizationId")}`,
+        });
+    }
+    /**
+     * Whether an active subscription unlocks a plan feature - the check that
+     * gates a plan-restricted module.
+     *
+     * Deliberately `false` rather than a throw when there is no subscription at
+     * all: "not entitled" is the same answer either way, and a feature gate
+     * should not need a try/catch around it.
+     */
+    async hasFeature(organizationId, feature) {
+        const result = await this.getSubscription(organizationId);
+        return result.hasActiveSubscription && (result.plan?.features.includes(feature) ?? false);
+    }
+}
+exports.EntitlementsResource = EntitlementsResource;

package/dist/cjs/server/resources/identity.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityResource = void 0;
+exports.createState = createState;
+const errors_js_1 = require("../../errors.js");
+const http_js_1 = require("../http.js");
+/** A URL-safe random string, suitable for `state` or a PKCE verifier. */
+function createState(byteLength = 32) {
+    const bytes = new Uint8Array(byteLength);
+    crypto.getRandomValues(bytes);
+    return base64UrlEncode(bytes);
+}
+function base64UrlEncode(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(value) {
+    const padded = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+    const binary = atob(padded);
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+}
+/**
+ * "Login with Connect" - the OAuth2 handshake, and the session that outlives
+ * it.
+ *
+ * The whole flow is five calls: `authorizeUrl` to send them out,
+ * `exchangeCode` when they come back, `verifyIdToken` once, then `getUser` on
+ * each later request and `logout` at the end.
+ */
+class IdentityResource {
+    transport;
+    clientId;
+    appBaseUrl;
+    constructor(transport, clientId, appBaseUrl) {
+        this.transport = transport;
+        this.clientId = clientId;
+        this.appBaseUrl = appBaseUrl;
+    }
+    /** Step 1 - the URL to send the user's browser to. */
+    authorizeUrl(input) {
+        const url = new URL("/sso/authorize", this.appBaseUrl);
+        url.searchParams.set("client_id", this.requireClientId());
+        url.searchParams.set("redirect_uri", input.redirectUri);
+        url.searchParams.set("response_type", "code");
+        url.searchParams.set("scope", "openid");
+        url.searchParams.set("state", input.state);
+        if (input.prompt)
+            url.searchParams.set("prompt", input.prompt);
+        if (input.codeChallenge) {
+            url.searchParams.set("code_challenge", input.codeChallenge);
+            url.searchParams.set("code_challenge_method", "S256");
+        }
+        return url.toString();
+    }
+    /** Step 2 - trade the one-time `code` for a session. Server-side only. */
+    async exchangeCode(input) {
+        const wire = await this.post("/sso/token", {
+            grant_type: "authorization_code",
+            code: input.code,
+            redirect_uri: input.redirectUri,
+            code_verifier: input.codeVerifier,
+        });
+        return {
+            idToken: wire.id_token,
+            tokenType: wire.token_type,
+            expiresIn: wire.expires_in,
+            sessionToken: wire.session_token,
+            sessionTokenExpiresIn: wire.session_token_expires_in,
+            user: wire.user,
+            subscription: wire.subscription,
+            serviceRole: wire.serviceRole,
+        };
+    }
+    /**
+     * Step 3 - verify the `id_token` once, then discard it.
+     *
+     * HS256 over `header.payload`, keyed with your API key, plus the `exp` and
+     * `aud` checks. There is no JWKS to fetch: Connect stores only your key's
+     * sha256 hash, so the token is signed with the shared secret rather than an
+     * asymmetric key. Signature comparison goes through WebCrypto's own
+     * `verify`, which is why this is async - hand-rolling the compare is the
+     * step integrations most often get wrong.
+     */
+    async verifyIdToken(idToken) {
+        // Guarded before `.split`, because the failure this catches is a caller
+        // passing something that is not a token at all. Left ungurded it threw a
+        // raw TypeError, which is not a `ConnectError`, so every layer above
+        // reported it as an unexplained internal error.
+        if (typeof idToken !== "string" || idToken.length === 0) {
+            throw this.tokenError("id_token is missing");
+        }
+        const parts = idToken.split(".");
+        const [header, payload, signature] = parts;
+        if (parts.length !== 3 || !header || !payload || !signature) {
+            throw this.tokenError("id_token is not a well-formed JWT");
+        }
+        const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(this.transport.apiKey), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+        // Decoded before `verify`, and guarded for the same reason the emptiness
+        // check above is: `atob` throws a raw `InvalidCharacterError` on a
+        // signature that is not base64url, which is not a `ConnectError`, so a
+        // caller verifying a token it did not mint gets an unexplained 500 where
+        // it should get a clean 401.
+        let signatureBytes;
+        try {
+            signatureBytes = base64UrlDecode(signature);
+        }
+        catch {
+            throw this.tokenError("id_token signature is not valid base64url");
+        }
+        const valid = await crypto.subtle.verify("HMAC", key, signatureBytes, new TextEncoder().encode(`${header}.${payload}`));
+        if (!valid)
+            throw this.tokenError("id_token signature does not match this API key");
+        let claims;
+        try {
+            claims = JSON.parse(new TextDecoder().decode(base64UrlDecode(payload)));
+        }
+        catch {
+            throw this.tokenError("id_token payload is not valid JSON");
+        }
+        if (typeof claims.exp !== "number" || claims.exp * 1000 <= Date.now()) {
+            throw this.tokenError("id_token has expired");
+        }
+        if (claims.aud !== this.requireClientId()) {
+            throw this.tokenError("id_token was issued for a different client_id");
+        }
+        return claims;
+    }
+    /**
+     * Step 4 - who is signed in, right now. Same blocks as `exchangeCode`,
+     * re-resolved live, so a role change or a lapsed subscription shows up here
+     * without another sign-in.
+     *
+     * Any `ConnectError` with `isSessionExpired` means send them back through
+     * `authorizeUrl()`.
+     */
+    async getUser(sessionToken) {
+        const wire = await this.post("/sso/user", { session_token: sessionToken });
+        return {
+            user: wire.user,
+            subscription: wire.subscription,
+            serviceRole: wire.serviceRole,
+            sessionExpiresAt: wire.session_expires_at,
+        };
+    }
+    /**
+     * Step 5 - end the sign-in immediately rather than leaving it valid for the
+     * rest of its ~15-day life. Discard your own copy of `sessionToken` too;
+     * this does not do that for you.
+     *
+     * `scope` defaults to `"device"`: this sign-in, every other service signed
+     * into from the same browser, and Connect's own session on that one device.
+     * `"all"` ends every session on every device - an explicit "sign out
+     * everywhere" action only.
+     *
+     * Always succeeds. An unknown or already-revoked token is an
+     * indistinguishable no-op, so there is nothing to branch on.
+     */
+    async logout(sessionToken, options = {}) {
+        await this.post("/sso/logout", {
+            session_token: sessionToken,
+            scope: options.scope,
+        });
+    }
+    post(path, form) {
+        const spec = {
+            method: "POST",
+            path,
+            auth: "none",
+            form: {
+                ...form,
+                client_id: this.requireClientId(),
+                client_secret: this.transport.apiKey,
+            },
+        };
+        return (0, http_js_1.request)(this.transport, spec);
+    }
+    requireClientId() {
+        if (!this.clientId) {
+            throw new errors_js_1.ConnectError({
+                status: 0,
+                code: "missing_client_id",
+                message: "identity.* needs `clientId`. Pass it to `new ConnectClient({ clientId, apiKey })` - it is shown in this service's Setup tab once SSO is enabled.",
+                endpoint: "identity",
+            });
+        }
+        return this.clientId;
+    }
+    tokenError(message) {
+        return new errors_js_1.ConnectError({ status: 401, code: "invalid_token", message, endpoint: "verifyIdToken" });
+    }
+}
+exports.IdentityResource = IdentityResource;

package/dist/cjs/server/resources/logs.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogsResource = void 0;
+const http_js_1 = require("../http.js");
+/** Push feature events into the Console's audit log, filterable to your service. */
+class LogsResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Never throws. A logging call that takes down the code path it was
+     * observing is worse than a lost line, so a failure here is swallowed and
+     * reported through the return value.
+     *
+     * Pass `sessionToken` to attribute the event to the end user it belongs to.
+     * Both scopes on the stored entry come from something verified - the service
+     * from your API key, the user from that token, which Connect checks was
+     * minted for your service before attributing anything. `attributed` in the
+     * result says whether it resolved; a `false` there still means the line was
+     * stored, just without a user on it.
+     */
+    async write(input) {
+        const timestamp = input.timestamp instanceof Date ? input.timestamp.toISOString() : input.timestamp;
+        try {
+            const result = await (0, http_js_1.request)(this.transport, {
+                method: "POST",
+                path: "/logs",
+                json: { ...input, timestamp },
+            });
+            // `?? false` covers a Connect old enough to predate the field - an
+            // absent `attributed` means the server had no attribution to report,
+            // which is exactly what `false` says.
+            return { delivered: true, attributed: result?.attributed ?? false };
+        }
+        catch {
+            return { delivered: false, attributed: false };
+        }
+    }
+}
+exports.LogsResource = LogsResource;

package/dist/cjs/server/resources/otp.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OtpResource = void 0;
+const http_js_1 = require("../http.js");
+/** WhatsApp/SMS phone verification. */
+class OtpResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Send a code. As with `billing.consumeAddon`, an `Idempotency-Key` always
+     * goes along - a retried send would otherwise deliver a second message and
+     * invalidate the first code the user is looking at.
+     */
+    send(input, options = {}) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/otp/send",
+            json: input,
+            headers: { "idempotency-key": options.idempotencyKey ?? crypto.randomUUID() },
+        });
+    }
+    /** Check a 6-digit code against a `verificationId`. */
+    verify(input) {
+        return (0, http_js_1.request)(this.transport, { method: "POST", path: "/otp/verify", json: input });
+    }
+}
+exports.OtpResource = OtpResource;

package/dist/cjs/server/resources/sessions.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionsResource = void 0;
+const errors_js_1 = require("../../errors.js");
+const http_js_1 = require("../http.js");
+/**
+ * This Connect account's own login sessions - device, approximate location,
+ * timestamps - the same list Connect's own account settings page shows the
+ * user themselves.
+ *
+ * **Account-wide, not scoped to this service.** A Connect session is one
+ * browser's login to Connect, and it fans out to every partner service's own
+ * `sessionToken` - Connect has no per-service session concept to filter by.
+ * `list()` returns every session on the account, including ones that
+ * originated from a completely different, unrelated service. Requires the
+ * `sessions:manage` scope on your API key - unlike `identity`'s base `sso`
+ * capability, this is never granted to a zero-scope legacy key by default.
+ *
+ * Authenticated like `identity.*` - `client_id`+`client_secret`, never a
+ * Bearer key - because every call here is really "resolve identity from a
+ * `sessionToken`", the same shape `identity.getUser`/`identity.logout` are.
+ */
+class SessionsResource {
+    transport;
+    clientId;
+    constructor(transport, clientId) {
+        this.transport = transport;
+        this.clientId = clientId;
+    }
+    /** Every active session on the account behind `sessionToken`. `isCurrent` marks the one it was minted from. */
+    async list(sessionToken) {
+        const result = await this.post("/sso/sessions", {
+            session_token: sessionToken,
+        });
+        // See `AppsResource.list` - a collection unwrap has to survive a body
+        // that omits the key, or it becomes a browser-side crash two hops away.
+        return result.items ?? [];
+    }
+    /**
+     * Ends one specific session by id - not necessarily the one `sessionToken`
+     * itself was minted from. Cascades to every partner-service sign-in that
+     * originated from that same browser, same as Connect's own "sign out this
+     * device".
+     */
+    async revoke(sessionToken, sessionId) {
+        await this.post("/sso/sessions/revoke", {
+            session_token: sessionToken,
+            sessionId,
+        });
+    }
+    /** "Sign out everywhere else" - keeps the session `sessionToken` was minted from, ends every other one. */
+    async revokeOthers(sessionToken) {
+        return this.post("/sso/sessions/revoke-others", {
+            session_token: sessionToken,
+        });
+    }
+    post(path, form) {
+        const spec = {
+            method: "POST",
+            path,
+            auth: "none",
+            form: {
+                ...form,
+                client_id: this.requireClientId(),
+                client_secret: this.transport.apiKey,
+            },
+        };
+        return (0, http_js_1.request)(this.transport, spec);
+    }
+    requireClientId() {
+        if (!this.clientId) {
+            throw new errors_js_1.ConnectError({
+                status: 0,
+                code: "missing_client_id",
+                message: "sessions.* needs `clientId`. Pass it to `new ConnectClient({ clientId, apiKey })` - it is shown in this service's Setup tab once SSO is enabled.",
+                endpoint: "sessions",
+            });
+        }
+        return this.clientId;
+    }
+}
+exports.SessionsResource = SessionsResource;

package/dist/cjs/types.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Wire types for the `/api/v1/service/*` surface - the service-partner API,
+ * and the only thing this SDK covers.
+ *
+ * Hand-written rather than generated so the published package carries no
+ * dependency on Connect's internals. `src/conformance.test.ts` type-checks
+ * these against the server's own DTOs, so drift fails the build here instead
+ * of surfacing as a runtime surprise in a partner's integration.
+ *
+ * Dates cross the wire as ISO 8601 strings and are left that way - parsing
+ * them into `Date` would be a lossy guess about what the caller wants, and
+ * `new Date(value)` is right there.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/cli/bin.js

@@ -0,0 +1,13 @@
+/**
+ * The `connect-sdk` executable.
+ *
+ * A thin wrapper so `init.ts` stays importable and testable - a module that
+ * calls `process.exit` at import time cannot be unit tested, and this is the
+ * only file that does.
+ *
+ * The shebang is added by `scripts/finalize-dist.ts`: TypeScript strips leading
+ * comments it does not recognise as directives, and a `bin` without one is run
+ * by the shell rather than by Node.
+ */
+import { main } from "./init.js";
+process.exit(main(process.argv.slice(2)));