@clawnify/connections 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# @clawnify/connections
+
+One declaration, one accessor for every credential a Clawnify app needs.
+
+```ts
+import { connect, secret, describe } from "@clawnify/connections";
+
+// OAuth or managed — app code is identical either way:
+const accounts = await connect("metaads", env).get("/me/adaccounts", { fields: "name,id" });
+const rows     = await connect("googleads", env).query("SELECT customer.id FROM customer");
+
+// Provider keys / secrets:
+const key = secret("OPENROUTER_API_KEY", env);
+
+// What's wired, for an agent to read before writing code:
+const status = await describe(env, env.CLAWNIFY_ORG_ID, REQUIRES);
+```
+
+`env` is your worker's `env` (it carries the `CREDENTIALS` binding and any
+injected keys). Pass `orgId` explicitly or let it default to
+`env.CLAWNIFY_ORG_ID`.
+
+## Why
+
+Before this, every app hand-wrote its credential plumbing: which integration is
+OAuth-direct vs. managed, the exact env var name for each key, the response
+shape of each managed call. That knowledge belongs in **one** place. This SDK is
+the accessor; [`@clawnify/integrations`](../integrations) is the descriptor
+registry it reads. The broker that actually holds a credential is invisible to
+your app — `connect()` routes to it; `describe()` never names it.
+
+## The registry is an enhancement, not a gate
+
+A descriptor exists only to give an integration a **typed, ergonomic client**
+(`connect("googleads").query(gaql)`). Functionality never depends on one:
+
+- `connect("anything", env)` with no descriptor returns a `GenericClient` with
+  `token()` and `run(action, args)` — every integration supports those two
+  operations, so a toolkit **just added in the dashboard works immediately**.
+- `secret(name, env)` reads any key by name — names come from the dashboard,
+  not from a release.
+- `describe(env, org, requires)` reports unregistered integrations too
+  (connectivity + a generic accessor).
+
+So you publish a new version of `@clawnify/integrations` **only when you want to
+upgrade a specific integration from generic to first-class** — never just to
+make a new integration usable. Adding the descriptor is opt-in sugar for the
+handful of integrations where a typed client earns its keep.
+
+## API
+
+| Call | Returns | Use for |
+|------|---------|---------|
+| `connect(service, env, orgId?)` | typed client (`ServiceClients[service]`) | OAuth / managed integrations |
+| `secret(name, env)` | `string \| null` | provider keys & user secrets |
+| `isConnected(service, env, orgId?)` | `Promise<boolean>` | gating a feature on a connection |
+| `describe(env, orgId?, requires?)` | `Promise<DescribeEntry[]>` | agent-legible readiness snapshot |
+
+### Declaring requirements
+
+In `clawnify.json`:
+
+```jsonc
+{
+  "requires": [
+    { "service": "metaads",  "as": "integration" },
+    { "service": "googleads", "as": "integration" },
+    { "name": "OPENROUTER_API_KEY", "as": "key" }
+  ]
+}
+```
+
+`requires` only **declares** — it never provisions. Connections and keys are
+added in the Clawnify dashboard; when one is missing, `describe()` returns the
+exact dashboard step in its `hint`.
+
+## Local dev
+
+Two ways to run off-platform:
+
+1. **One org token (recommended).** Put your org's Clawnify token in `.dev.vars`:
+
+   ```
+   CLAWNIFY_TOKEN=clw_…
+   ```
+
+   With no in-process `CREDENTIALS` binding, the SDK resolves connections over
+   HTTP via the Clawnify API — `connect("googleads")`, `connect("metaads")`,
+   `describe()` all hit your **real** org connections, including managed ones.
+   The org is derived from the token server-side, so you don't set an org id and
+   you paste no per-service secrets. Override the API base with `CLAWNIFY_API_URL`.
+
+2. **Bare env tokens.** Without `CLAWNIFY_TOKEN`, the SDK falls back to
+   `METAADS_BEARER_TOKEN` / `OPENROUTER_API_KEY` / etc. from `.dev.vars`. Managed
+   integrations can't resolve this way and report not-ready.
+
+In deployed apps neither is needed — Clawnify injects the in-process binding.

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+import { ConnectionKind, ServiceClients } from '@clawnify/integrations';
+export * from '@clawnify/integrations';
+
+/**
+ * @clawnify/connections — the accessor SDK.
+ *
+ * Three calls cover every credential an app needs:
+ *
+ *   connect("googleads", env)        → a typed client (oauth or managed alike)
+ *   secret("OPENROUTER_API_KEY", env)→ an injected provider key / secret
+ *   describe(env, orgId, requires)   → agent-legible "what's wired" snapshot
+ *
+ * App code is identical whether a connection is managed or self-served, OAuth or
+ * API key, dynamic or static. The broker that actually holds a credential lives
+ * behind the Clawnify credentials binding and is never named here — `describe()`
+ * speaks only in capabilities (`oauth`/`managed`/`key`/`secret`).
+ */
+
+/**
+ * The credentials broker RPC contract — the Clawnify `CREDENTIALS` service
+ * binding injected into every app. These method names are Clawnify-internal;
+ * the provider behind them (managed or self-configured) is not part of the
+ * contract.
+ */
+interface CredentialBinding {
+    getToken(service: string, orgId: string): Promise<string | null>;
+    executeTool(service: string, toolSlug: string, args: Record<string, unknown>, orgId: string): Promise<{
+        data: unknown;
+        error: string | null;
+        successful: boolean;
+    }>;
+    listConnected(orgId: string): Promise<string[]>;
+}
+/** The slice of a worker's `env` the SDK reads. */
+interface ConnectionsEnv {
+    /** The in-process credentials binding. Present in deployed apps. */
+    CREDENTIALS?: CredentialBinding;
+    /** The org the app is serving, injected by the Clawnify builder. */
+    CLAWNIFY_ORG_ID?: string;
+    /**
+     * A Clawnify token: either the OAuth bearer `clawnify login` holds, or a
+     * long-lived org service token (clw_…). When set and no in-process
+     * CREDENTIALS binding exists, the SDK resolves connections over HTTP via the
+     * Clawnify API — so local `pnpm dev` / scripts reach real org connections
+     * with no per-service secrets. With an OAuth bearer spanning several orgs,
+     * CLAWNIFY_ORG_ID picks one; a service token fixes the org itself.
+     */
+    CLAWNIFY_TOKEN?: string;
+    /** Override the Clawnify API base for the HTTP binding (defaults to prod). */
+    CLAWNIFY_API_URL?: string;
+    /** Injected provider keys / secrets / local-dev token fallbacks. */
+    [key: string]: unknown;
+}
+/**
+ * An HTTP-backed {@link CredentialBinding} for environments without the
+ * in-process binding (local `pnpm dev`, scripts, Claude Code).
+ *
+ * `token` is either a Clawnify OAuth bearer (the session `clawnify login`
+ * holds) or a long-lived org service token (clw_…). With an OAuth bearer that
+ * belongs to several orgs, pass `orgId` to target one (sent as `x-org-id`);
+ * with a service token the org is fixed and `orgId` is ignored. Managed
+ * credentials stay server-side — only `getToken` returns a bearer.
+ */
+declare function clawnifyBinding(opts: {
+    token: string;
+    baseUrl?: string;
+    orgId?: string;
+}): CredentialBinding;
+/**
+ * Low-level client returned for any integration without a bespoke descriptor.
+ * Every integration supports these two operations, so a new dashboard
+ * integration is usable immediately — no descriptor, no package release.
+ */
+interface GenericClient {
+    /** Current access token (OAuth / API key) for this integration. */
+    token(): Promise<string | null>;
+    /** Run a managed action scoped to the org; returns its data, throws on failure. */
+    run(action: string, args?: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * Get a client for an integration.
+ *
+ * - Registered integrations return their typed client — `connect("googleads",
+ *   env)` is a GoogleAdsClient, no casting.
+ * - Any other (e.g. a toolkit just added in the dashboard) returns a
+ *   {@link GenericClient} with `token()` + `run()`. The registry is an
+ *   ergonomics layer, never a gate: functionality never depends on a release.
+ *
+ * @throws only when the service is a known key/secret — read those with secret().
+ */
+declare function connect<K extends keyof ServiceClients>(service: K, env: ConnectionsEnv, orgId?: string): ServiceClients[K];
+declare function connect(service: string, env: ConnectionsEnv, orgId?: string): GenericClient;
+/** Read an injected provider key / secret env var. Returns null when absent. */
+declare function secret(name: string, env: ConnectionsEnv): string | null;
+/** True when a usable credential exists for this service right now. */
+declare function isConnected(service: string, env: ConnectionsEnv, orgId?: string): Promise<boolean>;
+/** One entry in clawnify.json's `requires` block. */
+type RequireSpec = {
+    service: string;
+    as: "integration";
+} | {
+    name: string;
+    as: "key" | "secret";
+};
+/** Per-capability readiness, written for an agent to read before wiring code. */
+interface DescribeEntry {
+    /** Service id (integrations) or env var name (keys/secrets). */
+    id: string;
+    label: string;
+    kind: ConnectionKind;
+    /** Whether a credential is present for this capability. */
+    connected: boolean;
+    /** Whether app code can use it right now (same as connected today). */
+    ready: boolean;
+    /** One-line snippet showing how to access it in app code. */
+    accessor: string;
+    /** What to do when it isn't ready — always dashboard-driven. */
+    hint?: string;
+}
+/**
+ * Report what's wired for an org. Pass the app's `requires` to report exactly
+ * those capabilities (the agent-facing case); omit it to report every known
+ * integration's status for the org.
+ *
+ * Never names the underlying broker — only `kind` and readiness.
+ */
+declare function describe(env: ConnectionsEnv, orgId?: string, requires?: RequireSpec[]): Promise<DescribeEntry[]>;
+
+export { type ConnectionsEnv, type CredentialBinding, type DescribeEntry, type GenericClient, type RequireSpec, clawnifyBinding, connect, describe, isConnected, secret };

package/dist/index.js

@@ -0,0 +1,155 @@
+// src/index.ts
+import {
+  getDescriptor,
+  allDescriptors
+} from "@clawnify/integrations";
+export * from "@clawnify/integrations";
+var DEFAULT_API_BASE = "https://provision.clawnify.com";
+function clawnifyBinding(opts) {
+  const base = (opts.baseUrl ?? DEFAULT_API_BASE).replace(/\/+$/, "");
+  const headers = {
+    Authorization: `Bearer ${opts.token}`,
+    "Content-Type": "application/json",
+    ...opts.orgId ? { "x-org-id": opts.orgId } : {}
+  };
+  return {
+    async getToken(service) {
+      const res = await fetch(`${base}/v1/connections/token`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ service })
+      });
+      if (!res.ok) return null;
+      const j = await res.json();
+      return j.token ?? null;
+    },
+    async executeTool(service, toolSlug, args) {
+      const res = await fetch(`${base}/v1/connections/execute`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ service, action: toolSlug, args })
+      });
+      const j = await res.json().catch(() => ({}));
+      if (!res.ok) return { data: null, error: j.error ?? `connections ${res.status}`, successful: false };
+      return { data: j.data ?? null, error: j.error ?? null, successful: j.successful ?? true };
+    },
+    async listConnected() {
+      const res = await fetch(`${base}/v1/connections/connected`, { headers });
+      if (!res.ok) return [];
+      const j = await res.json();
+      return j.services ?? [];
+    }
+  };
+}
+function resolveBinding(env) {
+  if (env.CREDENTIALS) return { binding: env.CREDENTIALS, remote: false };
+  const token = typeof env.CLAWNIFY_TOKEN === "string" ? env.CLAWNIFY_TOKEN : "";
+  if (token) {
+    const baseUrl = typeof env.CLAWNIFY_API_URL === "string" ? env.CLAWNIFY_API_URL : void 0;
+    const orgId = typeof env.CLAWNIFY_ORG_ID === "string" ? env.CLAWNIFY_ORG_ID : void 0;
+    return { binding: clawnifyBinding({ token, baseUrl, orgId }), remote: true };
+  }
+  return { remote: false };
+}
+function resolveOrg(env, orgId) {
+  return orgId ?? env.CLAWNIFY_ORG_ID ?? null;
+}
+function buildContext(service, env, orgId) {
+  const { binding, remote } = resolveBinding(env);
+  const canBroker = !!binding && (remote || !!orgId);
+  return {
+    orgId,
+    managed: canBroker,
+    env,
+    async token() {
+      if (binding && canBroker) {
+        try {
+          return await binding.getToken(service, orgId ?? "");
+        } catch {
+          return null;
+        }
+      }
+      const up = service.toUpperCase();
+      const local = env[`${up}_BEARER_TOKEN`] ?? env[`${up}_ACCESS_TOKEN`];
+      return typeof local === "string" ? local : null;
+    },
+    async run(action, args = {}) {
+      if (!binding || !canBroker) {
+        throw new Error(`"${service}" needs the Clawnify credentials binding or CLAWNIFY_TOKEN`);
+      }
+      const r = await binding.executeTool(service, action, args, orgId ?? "");
+      if (!r.successful) throw new Error(r.error ?? `${service} action "${action}" failed`);
+      return r.data;
+    }
+  };
+}
+function connect(service, env, orgId) {
+  const ctx = buildContext(service, env, resolveOrg(env, orgId));
+  const desc = getDescriptor(service);
+  if (desc?.client) return desc.client(ctx);
+  if (desc && (desc.kind === "key" || desc.kind === "secret")) {
+    throw new Error(`"${service}" is a ${desc.kind}; read it with secret("${desc.envName ?? service}")`);
+  }
+  return { token: ctx.token, run: ctx.run };
+}
+function secret(name, env) {
+  const v = env[name];
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+async function isConnected(service, env, orgId) {
+  const desc = getDescriptor(service);
+  if (!desc) return false;
+  const org = resolveOrg(env, orgId);
+  if (desc.kind === "key" || desc.kind === "secret") {
+    return !!secret(desc.envName ?? service, env);
+  }
+  const { binding, remote } = resolveBinding(env);
+  if (binding && (remote || org)) {
+    try {
+      if ((await binding.listConnected(org ?? "")).includes(service)) return true;
+    } catch {
+    }
+  }
+  return !!await buildContext(service, env, org).token();
+}
+async function describe(env, orgId, requires) {
+  const org = resolveOrg(env, orgId);
+  const fromDescriptor = (d) => {
+    const isKey = d.kind === "key" || d.kind === "secret";
+    return { id: isKey ? d.envName ?? d.service : d.service, label: d.label, kind: d.kind, accessor: d.accessor, isKey };
+  };
+  let items;
+  if (requires?.length) {
+    items = requires.map((r) => {
+      if ("name" in r) {
+        const d2 = getDescriptor(r.name);
+        return d2 ? fromDescriptor(d2) : { id: r.name, label: r.name, kind: r.as, accessor: `secret("${r.name}")`, isKey: true };
+      }
+      const d = getDescriptor(r.service);
+      return d ? fromDescriptor(d) : { id: r.service, label: r.service, kind: "managed", accessor: `connect("${r.service}")`, isKey: false };
+    });
+  } else {
+    items = allDescriptors().map(fromDescriptor);
+  }
+  let connectedList = [];
+  const { binding, remote } = resolveBinding(env);
+  if (binding && (remote || org) && items.some((i) => !i.isKey)) {
+    try {
+      connectedList = await binding.listConnected(org ?? "");
+    } catch {
+    }
+  }
+  return items.map((i) => {
+    const has = i.isKey ? !!secret(i.id, env) : connectedList.includes(i.id);
+    const hint = has ? void 0 : i.isKey ? `Add ${i.id} in the dashboard \u2192 API Keys / Environment Variables.` : `Connect ${i.label} in the dashboard \u2192 Integrations.`;
+    return { id: i.id, label: i.label, kind: i.kind, connected: has, ready: has, accessor: i.accessor, hint };
+  });
+}
+export {
+  clawnifyBinding,
+  connect,
+  describe,
+  isConnected,
+  secret
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @clawnify/connections — the accessor SDK.\n *\n * Three calls cover every credential an app needs:\n *\n *   connect(\"googleads\", env)        → a typed client (oauth or managed alike)\n *   secret(\"OPENROUTER_API_KEY\", env)→ an injected provider key / secret\n *   describe(env, orgId, requires)   → agent-legible \"what's wired\" snapshot\n *\n * App code is identical whether a connection is managed or self-served, OAuth or\n * API key, dynamic or static. The broker that actually holds a credential lives\n * behind the Clawnify credentials binding and is never named here — `describe()`\n * speaks only in capabilities (`oauth`/`managed`/`key`/`secret`).\n */\n\nimport {\n  getDescriptor,\n  allDescriptors,\n  type ServiceClients,\n  type ConnectionDescriptor,\n  type ConnectionKind,\n  type AccessContext,\n} from \"@clawnify/integrations\";\n\n// Re-export the descriptor layer so consumers get client types (MetaAdsClient,\n// GoogleAdsRow, …) and descriptor types from one import.\nexport * from \"@clawnify/integrations\";\n\n/**\n * The credentials broker RPC contract — the Clawnify `CREDENTIALS` service\n * binding injected into every app. These method names are Clawnify-internal;\n * the provider behind them (managed or self-configured) is not part of the\n * contract.\n */\nexport interface CredentialBinding {\n  getToken(service: string, orgId: string): Promise<string | null>;\n  executeTool(\n    service: string,\n    toolSlug: string,\n    args: Record<string, unknown>,\n    orgId: string,\n  ): Promise<{ data: unknown; error: string | null; successful: boolean }>;\n  listConnected(orgId: string): Promise<string[]>;\n}\n\n/** The slice of a worker's `env` the SDK reads. */\nexport interface ConnectionsEnv {\n  /** The in-process credentials binding. Present in deployed apps. */\n  CREDENTIALS?: CredentialBinding;\n  /** The org the app is serving, injected by the Clawnify builder. */\n  CLAWNIFY_ORG_ID?: string;\n  /**\n   * A Clawnify token: either the OAuth bearer `clawnify login` holds, or a\n   * long-lived org service token (clw_…). When set and no in-process\n   * CREDENTIALS binding exists, the SDK resolves connections over HTTP via the\n   * Clawnify API — so local `pnpm dev` / scripts reach real org connections\n   * with no per-service secrets. With an OAuth bearer spanning several orgs,\n   * CLAWNIFY_ORG_ID picks one; a service token fixes the org itself.\n   */\n  CLAWNIFY_TOKEN?: string;\n  /** Override the Clawnify API base for the HTTP binding (defaults to prod). */\n  CLAWNIFY_API_URL?: string;\n  /** Injected provider keys / secrets / local-dev token fallbacks. */\n  [key: string]: unknown;\n}\n\nconst DEFAULT_API_BASE = \"https://provision.clawnify.com\";\n\n/**\n * An HTTP-backed {@link CredentialBinding} for environments without the\n * in-process binding (local `pnpm dev`, scripts, Claude Code).\n *\n * `token` is either a Clawnify OAuth bearer (the session `clawnify login`\n * holds) or a long-lived org service token (clw_…). With an OAuth bearer that\n * belongs to several orgs, pass `orgId` to target one (sent as `x-org-id`);\n * with a service token the org is fixed and `orgId` is ignored. Managed\n * credentials stay server-side — only `getToken` returns a bearer.\n */\nexport function clawnifyBinding(opts: { token: string; baseUrl?: string; orgId?: string }): CredentialBinding {\n  const base = (opts.baseUrl ?? DEFAULT_API_BASE).replace(/\\/+$/, \"\");\n  const headers: Record<string, string> = {\n    Authorization: `Bearer ${opts.token}`,\n    \"Content-Type\": \"application/json\",\n    ...(opts.orgId ? { \"x-org-id\": opts.orgId } : {}),\n  };\n  return {\n    async getToken(service) {\n      const res = await fetch(`${base}/v1/connections/token`, {\n        method: \"POST\",\n        headers,\n        body: JSON.stringify({ service }),\n      });\n      if (!res.ok) return null;\n      const j = (await res.json()) as { token?: string | null };\n      return j.token ?? null;\n    },\n    async executeTool(service, toolSlug, args) {\n      const res = await fetch(`${base}/v1/connections/execute`, {\n        method: \"POST\",\n        headers,\n        body: JSON.stringify({ service, action: toolSlug, args }),\n      });\n      const j = (await res.json().catch(() => ({}))) as {\n        data?: unknown;\n        error?: string | null;\n        successful?: boolean;\n      };\n      if (!res.ok) return { data: null, error: j.error ?? `connections ${res.status}`, successful: false };\n      return { data: j.data ?? null, error: j.error ?? null, successful: j.successful ?? true };\n    },\n    async listConnected() {\n      const res = await fetch(`${base}/v1/connections/connected`, { headers });\n      if (!res.ok) return [];\n      const j = (await res.json()) as { services?: string[] };\n      return j.services ?? [];\n    },\n  };\n}\n\n/**\n * The binding to use this request: the in-process one if present, else an HTTP\n * binding built from CLAWNIFY_TOKEN. `remote` binding resolves the org from the\n * token, so it works without a local org id.\n */\nfunction resolveBinding(env: ConnectionsEnv): { binding?: CredentialBinding; remote: boolean } {\n  if (env.CREDENTIALS) return { binding: env.CREDENTIALS, remote: false };\n  const token = typeof env.CLAWNIFY_TOKEN === \"string\" ? env.CLAWNIFY_TOKEN : \"\";\n  if (token) {\n    const baseUrl = typeof env.CLAWNIFY_API_URL === \"string\" ? env.CLAWNIFY_API_URL : undefined;\n    const orgId = typeof env.CLAWNIFY_ORG_ID === \"string\" ? env.CLAWNIFY_ORG_ID : undefined;\n    return { binding: clawnifyBinding({ token, baseUrl, orgId }), remote: true };\n  }\n  return { remote: false };\n}\n\nfunction resolveOrg(env: ConnectionsEnv, orgId?: string): string | null {\n  return orgId ?? env.CLAWNIFY_ORG_ID ?? null;\n}\n\nfunction buildContext(service: string, env: ConnectionsEnv, orgId: string | null): AccessContext {\n  const { binding, remote } = resolveBinding(env);\n  // A remote binding derives the org from the token, so it works without a\n  // local org id; an in-process binding needs one.\n  const canBroker = !!binding && (remote || !!orgId);\n  return {\n    orgId,\n    managed: canBroker,\n    env: env as Record<string, string | undefined>,\n    async token() {\n      if (binding && canBroker) {\n        try {\n          return await binding.getToken(service, orgId ?? \"\");\n        } catch {\n          return null;\n        }\n      }\n      // Local-dev fallback: a bare token in env, e.g. METAADS_BEARER_TOKEN.\n      const up = service.toUpperCase();\n      const local = env[`${up}_BEARER_TOKEN`] ?? env[`${up}_ACCESS_TOKEN`];\n      return typeof local === \"string\" ? local : null;\n    },\n    async run(action, args = {}) {\n      if (!binding || !canBroker) {\n        throw new Error(`\"${service}\" needs the Clawnify credentials binding or CLAWNIFY_TOKEN`);\n      }\n      const r = await binding.executeTool(service, action, args, orgId ?? \"\");\n      if (!r.successful) throw new Error(r.error ?? `${service} action \"${action}\" failed`);\n      return r.data;\n    },\n  };\n}\n\n/**\n * Low-level client returned for any integration without a bespoke descriptor.\n * Every integration supports these two operations, so a new dashboard\n * integration is usable immediately — no descriptor, no package release.\n */\nexport interface GenericClient {\n  /** Current access token (OAuth / API key) for this integration. */\n  token(): Promise<string | null>;\n  /** Run a managed action scoped to the org; returns its data, throws on failure. */\n  run(action: string, args?: Record<string, unknown>): Promise<unknown>;\n}\n\n/**\n * Get a client for an integration.\n *\n * - Registered integrations return their typed client — `connect(\"googleads\",\n *   env)` is a GoogleAdsClient, no casting.\n * - Any other (e.g. a toolkit just added in the dashboard) returns a\n *   {@link GenericClient} with `token()` + `run()`. The registry is an\n *   ergonomics layer, never a gate: functionality never depends on a release.\n *\n * @throws only when the service is a known key/secret — read those with secret().\n */\nexport function connect<K extends keyof ServiceClients>(service: K, env: ConnectionsEnv, orgId?: string): ServiceClients[K];\nexport function connect(service: string, env: ConnectionsEnv, orgId?: string): GenericClient;\nexport function connect(service: string, env: ConnectionsEnv, orgId?: string): unknown {\n  const ctx = buildContext(service, env, resolveOrg(env, orgId));\n  const desc = getDescriptor(service);\n  if (desc?.client) return desc.client(ctx);\n  if (desc && (desc.kind === \"key\" || desc.kind === \"secret\")) {\n    throw new Error(`\"${service}\" is a ${desc.kind}; read it with secret(\"${desc.envName ?? service}\")`);\n  }\n  return { token: ctx.token, run: ctx.run } satisfies GenericClient;\n}\n\n/** Read an injected provider key / secret env var. Returns null when absent. */\nexport function secret(name: string, env: ConnectionsEnv): string | null {\n  const v = env[name];\n  return typeof v === \"string\" && v.length > 0 ? v : null;\n}\n\n/** True when a usable credential exists for this service right now. */\nexport async function isConnected(service: string, env: ConnectionsEnv, orgId?: string): Promise<boolean> {\n  const desc = getDescriptor(service);\n  if (!desc) return false;\n  const org = resolveOrg(env, orgId);\n  if (desc.kind === \"key\" || desc.kind === \"secret\") {\n    return !!secret(desc.envName ?? service, env);\n  }\n  const { binding, remote } = resolveBinding(env);\n  if (binding && (remote || org)) {\n    try {\n      if ((await binding.listConnected(org ?? \"\")).includes(service)) return true;\n    } catch {\n      /* fall through to token probe */\n    }\n  }\n  return !!(await buildContext(service, env, org).token());\n}\n\n/** One entry in clawnify.json's `requires` block. */\nexport type RequireSpec =\n  | { service: string; as: \"integration\" }\n  | { name: string; as: \"key\" | \"secret\" };\n\n/** Per-capability readiness, written for an agent to read before wiring code. */\nexport interface DescribeEntry {\n  /** Service id (integrations) or env var name (keys/secrets). */\n  id: string;\n  label: string;\n  kind: ConnectionKind;\n  /** Whether a credential is present for this capability. */\n  connected: boolean;\n  /** Whether app code can use it right now (same as connected today). */\n  ready: boolean;\n  /** One-line snippet showing how to access it in app code. */\n  accessor: string;\n  /** What to do when it isn't ready — always dashboard-driven. */\n  hint?: string;\n}\n\n/**\n * Report what's wired for an org. Pass the app's `requires` to report exactly\n * those capabilities (the agent-facing case); omit it to report every known\n * integration's status for the org.\n *\n * Never names the underlying broker — only `kind` and readiness.\n */\nexport async function describe(\n  env: ConnectionsEnv,\n  orgId?: string,\n  requires?: RequireSpec[],\n): Promise<DescribeEntry[]> {\n  const org = resolveOrg(env, orgId);\n\n  // Normalize the work list. A required service with no descriptor is reported\n  // generically (still fully usable via connect()'s GenericClient) — the\n  // registry enriches, it never gates.\n  type Item = { id: string; label: string; kind: ConnectionKind; accessor: string; isKey: boolean };\n  const fromDescriptor = (d: ConnectionDescriptor): Item => {\n    const isKey = d.kind === \"key\" || d.kind === \"secret\";\n    return { id: isKey ? d.envName ?? d.service : d.service, label: d.label, kind: d.kind, accessor: d.accessor, isKey };\n  };\n\n  let items: Item[];\n  if (requires?.length) {\n    items = requires.map((r) => {\n      if (\"name\" in r) {\n        const d = getDescriptor(r.name);\n        return d ? fromDescriptor(d) : { id: r.name, label: r.name, kind: r.as, accessor: `secret(\"${r.name}\")`, isKey: true };\n      }\n      const d = getDescriptor(r.service);\n      // Unknown integration: kind is genuinely unknown without a descriptor;\n      // \"managed\" is the broadest accessor (token() + run() both work).\n      return d ? fromDescriptor(d) : { id: r.service, label: r.service, kind: \"managed\" as ConnectionKind, accessor: `connect(\"${r.service}\")`, isKey: false };\n    });\n  } else {\n    items = allDescriptors().map(fromDescriptor);\n  }\n\n  // One broker round-trip for all integration kinds.\n  let connectedList: string[] = [];\n  const { binding, remote } = resolveBinding(env);\n  if (binding && (remote || org) && items.some((i) => !i.isKey)) {\n    try {\n      connectedList = await binding.listConnected(org ?? \"\");\n    } catch {\n      /* leave empty — everything reports not-connected */\n    }\n  }\n\n  return items.map((i) => {\n    const has = i.isKey ? !!secret(i.id, env) : connectedList.includes(i.id);\n    const hint = has\n      ? undefined\n      : i.isKey\n        ? `Add ${i.id} in the dashboard → API Keys / Environment Variables.`\n        : `Connect ${i.label} in the dashboard → Integrations.`;\n    return { id: i.id, label: i.label, kind: i.kind, connected: has, ready: has, accessor: i.accessor, hint };\n  });\n}\n"],"mappings":"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","names":["d"]}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@clawnify/connections",
+  "version": "0.1.0",
+  "description": "One-declaration, one-accessor credentials SDK for Clawnify apps. connect(service) returns a typed client, secret(name) reads an injected key, and describe(org) tells an agent what's wired — all over the Clawnify credentials binding, with the broker kept invisible.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@clawnify/integrations": "0.1.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260405.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
+}