@clawnify/connections
v0.7.0
Published
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 i
Readme
@clawnify/connections
One declaration, one accessor for every credential a Clawnify app needs.
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 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 aGenericClientwithrawRequest()/rawFile()(the provider's own API, through the broker),token()andrun(action, args). Every integration supports these, 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?, account? }) | typed client (ServiceClients[service]) | OAuth / managed integrations; a bare string is still the org id |
| accounts(service, env, orgId?) | Promise<ConnectedAccount[]> | letting a user pick one of the org's accounts of a service |
| 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 |
Calling a provider's own API
The preferred call for an integration without a typed client is
rawRequest: one request to the provider's documented API, signed with the
org's connection by the broker. It is the same call whoever holds the
credential, so the app stays provider-agnostic. Run a broker action with
run() only where the proxy can't do the job.
const drive = connect("googledrive", env);
const list = await drive.rawRequest({
method: "GET",
endpoint: "/files",
parameters: [{ name: "q", value: `'${folderId}' in parents`, in: "query" }],
});
// An answer that is a file comes back as a link to its bytes (about an hour).
const piece = await drive.rawFile({
method: "GET",
endpoint: `/files/${fileId}?alt=media`,
parameters: [{ name: "Range", value: "bytes=0-1048575", in: "header" }],
}); // { url, contentType, size, expiresAt, status: 206, headers: { "content-range": … } }endpointis relative to the provider's API base, which can carry a version (Google Drive's ishttps://www.googleapis.com/drive/v3, so/files).rawRequestthrows on a provider error (status 400 and up), with the provider's message, and throws for a file answer: read that withrawFile.- A managed connection refuses a file over 250 MB in one answer: read it in
pieces with a
Rangeheader.
Several accounts of one service
An org can connect more than one account of some integrations (two Instagram
accounts, two X accounts). Without account, calls use the org's default
connection, as they always did. To use a specific one, list them and pass the
chosen account back:
const list = await accounts("instagram", env); // [{ account, label: "@rubenlen10", isDefault }, …]
await connect("instagram", env, { account: channel.accountId }).run("INSTAGRAM_POST_IG_USER_MEDIA", args);account is the provider's own id for the account, so it survives a
disconnect and reconnect. An account the org hasn't connected fails with a
"connect or reconnect it" error rather than falling back to the default.
Declaring requirements
In clawnify.json:
{
"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:
One org token (recommended). Put your org's Clawnify token in
.dev.vars:CLAWNIFY_TOKEN=clw_…With no in-process
CREDENTIALSbinding, 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 withCLAWNIFY_API_URL.Bare env tokens. Without
CLAWNIFY_TOKEN, the SDK falls back toMETAADS_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.
