@akai-workflow-builder/cli-sdk 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@akai-workflow-builder/cli-sdk` are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.1.4]
+
+### Added
+
+- `defineConnection()` — declare a connection umbrella that groups CLIs sharing
+  one auth surface (e.g. `google` groups gmail + gsheet). Returns a frozen,
+  WeakSet-branded `ConnectionDef`; hand-crafted objects carrying the brand are
+  rejected by `isAkaiConnection`.
+- `isAkaiConnection(x)` — type-guard that recognises only defs produced by
+  `defineConnection()` (registry-backed, not brand-sniffing).
+- New exported types: `ConnectionSpec`, `ConnectionDef`, `ConnectionOAuthConfig`,
+  `OAuthAdminField`, `ConnectionAuthKind`, `TokenEndpointAuthMethod`,
+  `RefreshStrategy`.
+- `AkaiConnectionError` — `AkaiSpecError` subclass thrown by `defineConnection()`
+  on invalid input; carries `path` + `issues` in `meta` for structured diagnostics.
+- `authorizeUrl`/`tokenUrl` are validated https-only; `http:` and non-http schemes
+  (including `javascript:`) are rejected at definition time.
+
 ## [0.1.3]
 
 ### Added

package/README.md

@@ -79,6 +79,74 @@ export default defineCLI({
 
 A full worked example with five read-only tools and a smoke runner lives in the repository under `examples/zendesk/` (not bundled in the published package; see the source tree).
 
+### Defining a connection
+
+A **connection** is the umbrella identity that groups CLIs sharing one auth surface — e.g. `google` groups Gmail and Sheets. Declare it with `defineConnection`, symmetric to `defineCLI`:
+
+```ts
+import { defineConnection } from '@akai-workflow-builder/cli-sdk';
+
+export default defineConnection({
+  slug: 'google',                 // groups CLIs that set connectionSlug: 'google'
+  name: 'Google Workspace',       // umbrella display name
+  vendor: 'Google',
+  blurb: 'Gmail, Sheets, Docs, Drive and Calendar in one connection.',
+  longDesc: 'Connect once with OAuth; every Google CLI shares the authorization.',
+  authKind: 'oauth2',
+  oauth: { /* see below */ },
+});
+```
+
+CLIs link to it through the **existing** `defineCLI` — set `connectionSlug`:
+
+```ts
+const gmail  = defineCLI({ id: 'gmail',  connectionSlug: 'google', summary: '…', tools: { … } });
+const gsheet = defineCLI({ id: 'gsheet', connectionSlug: 'google', summary: '…', tools: { … } });
+```
+
+**When to declare one:** only when ≥2 CLIs share a slug and need a single umbrella identity. A **single-CLI connection needs no `defineConnection`** — its identity comes from that CLI's own metadata (`pdf`, `sandbox` and friends are unchanged).
+
+`defineConnection` owns one concern: **identity**. It does not own tool sourcing, OAuth secret glue, or UI cosmetics — those split by source:
+
+| Concern | Source |
+|---|---|
+| Identity (name / blurb / longDesc / instructions / vendor / authKind) | `defineConnection` |
+| OAuth shape (authorize/token URLs, scopes, pkce, params, refresh, admin fields) | `defineConnection.oauth` |
+| OAuth secret VALUES, token storage, encryption, refresh hooks | akai-app, keyed by slug |
+| UI cosmetics (hue / mark / logo) | akai-app, keyed by slug |
+
+A complete runnable example is in [`examples/google`](./examples/google) — `defineConnection` plus two CLIs (`gmail`, `gsheet`) grouped under it.
+
+### OAuth connections
+
+When `authKind` is `oauth2`, declare an `oauth` block. **The manifest declares shape; akai-app owns values:**
+
+```ts
+oauth: {
+  authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+  tokenUrl: 'https://oauth2.googleapis.com/token',
+  scopes: [                                             // OAuth authorize scopes (≥1); distinct from per-CLI vendorScopes
+    'https://mail.google.com/',
+    'https://www.googleapis.com/auth/drive',
+  ],
+  pkce: true,                                           // Google requires PKCE; defaults to false
+  tokenEndpointAuthMethod: 'client_secret_post',        // default 'client_secret_basic'
+  extraAuthorizeParams: { access_type: 'offline', prompt: 'consent' },
+  refreshStrategy: 'cron',                              // 'cron' (background refresh) | 'jit' (refresh on next use); default 'cron'
+  adminFields: [
+    { key: 'GMAIL_CLIENT_ID',     label: 'Client ID' },
+    { key: 'GMAIL_CLIENT_SECRET', label: 'Client Secret', secret: true },
+  ],
+}
+```
+
+- `scopes` is the connection-level OAuth authorize scope set (≥1) the engine joins onto the authorize URL — distinct from a CLI's per-tool `vendorScopes`.
+- Set `pkce` when the provider requires it; set `extraAuthorizeParams` for static authorize params (Google's `access_type: 'offline'` to get a refresh token); leave `refreshStrategy` at the default `cron` (a background job refreshes the token before it expires) or set `jit` to refresh just-in-time on the next use.
+- `adminFields` declares **which** OAuth-app credentials an admin must enter (env-style `key` + UI `label`). The **VALUES are stored encrypted in akai-app, never in the manifest or the per-tenant image.**
+- Mark a field `secret: true` so akai-app masks the input in the admin form and redacts it from logs.
+
+See the `connection-identity` and `define-connection-oauth` migration specs (akai-app `app/connections/migration-specs/`) for per-field guidance.
+
 ---
 
 ## Core concepts
@@ -352,7 +420,7 @@ Every error extends `AkaiError`; the runtime maps each to a structured error env
 
 ### Typed tool errors
 
-Throw `AkaiToolError` from a handler to give an expected failure a stable classification and author-vetted wording. The host runtime brand-checks the thrown value by its serialized shape — `{ name: 'AkaiToolError', kind, message, meta? }` — with no SDK dependency, maps `kind` to an HTTP status, and returns `message` to the caller **verbatim**. Keep messages secret-free.
+Throw `AkaiToolError` from a handler to give an expected failure a stable classification and author-vetted wording. The host runtime brand-checks the thrown value by property access on its shape — `{ name: 'AkaiToolError', kind, message, meta? }` (it reads `message` via property access, not JSON serialization, since `Error.message` is non-enumerable) — with no SDK dependency, maps `kind` to an HTTP status, and returns `message` to the caller **verbatim**. Keep messages secret-free.
 
 ```ts
 import { AkaiToolError } from '@akai-workflow-builder/cli-sdk';
@@ -396,6 +464,17 @@ Untyped throws are classified generically (a 500 with a derived message).
 
 ---
 
+## Changelog
+
+### Unreleased
+
+- Add `defineConnection` — declare a connection's umbrella identity (`slug`, `name`, `vendor`, `blurb`, `longDesc`, `instructions`, `authKind`) plus its `oauth` shape. Returns a frozen, `WeakSet`-branded `ConnectionDef`. Symmetric to `defineCLI`.
+- Add the `oauth` block: `authorizeUrl`, `tokenUrl`, `scopes`, `pkce`, `tokenEndpointAuthMethod`, `extraAuthorizeParams`, `refreshStrategy`, and `adminFields` (the OAuth-app credentials an admin enters; values stay in akai-app). Validated for valid URLs, non-empty `scopes`, env-style admin keys, and `adminFields` presence when `authKind` is `oauth2`.
+- New exports: `defineConnection`, `isAkaiConnection`, `AkaiConnectionError`, and types `ConnectionSpec`, `ConnectionDef`, `ConnectionOAuthConfig`, `OAuthAdminField`, `ConnectionAuthKind`, `RefreshStrategy`, `TokenEndpointAuthMethod`.
+- New runnable example: `examples/google` (a connection grouping `gmail` + `gsheet`).
+
+---
+
 ## License
 
 MIT — see [`LICENSE`](./LICENSE).

package/dist/ctx/build-ctx.d.ts

@@ -30,6 +30,8 @@ export interface BuildCtxParams {
      * throws (no output channel provisioned).
      */
     readonly outputDir?: string;
+    /** Surfaced as `ctx.oauth.accessToken`. */
+    readonly oauthAccessToken?: string;
 }
 /**
  * Assemble a frozen {@link ToolCtx} for one tool invocation: resolves

package/dist/ctx/build-ctx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-ctx.d.ts","sourceRoot":"","sources":["../../src/ctx/build-ctx.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAGtB,OAAO,KAAK,EAAc,MAAM,EAAiB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG1F;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6GAA6G;IAC7G,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,sGAAsG;IACtG,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AA4CD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAoDxD"}
+{"version":3,"file":"build-ctx.d.ts","sourceRoot":"","sources":["../../src/ctx/build-ctx.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAGtB,OAAO,KAAK,EAAc,MAAM,EAAiB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG1F;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6GAA6G;IAC7G,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,sGAAsG;IACtG,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AA4CD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAuDxD"}

package/dist/ctx/build-ctx.js

@@ -86,5 +86,8 @@ export function buildCtx(params) {
         safePath,
         readFile,
         writeFile,
+        ...(params.oauthAccessToken !== undefined
+            ? { oauth: { accessToken: params.oauthAccessToken } }
+            : {}),
     });
 }

package/dist/define-cli.js

@@ -35,6 +35,13 @@ const CLISpecShape = z
         error: (issue) => `invalid id ${JSON.stringify(issue.input)}: lowercase letters/digits/hyphens/underscores only, must start with a letter`,
     }),
     name: z.string({ error: 'name is required' }).min(1, { error: 'name is required' }),
+    connectionSlug: z
+        .string({ error: 'connectionSlug must be a string if provided' })
+        .min(1, { error: 'connectionSlug must not be empty if provided' })
+        .regex(CLI_ID_RE, {
+        error: (issue) => `invalid connectionSlug ${JSON.stringify(issue.input)}: lowercase letters/digits/hyphens/underscores only, must start with a letter`,
+    })
+        .optional(),
     vendor: z
         .string({ error: 'vendor must be a string if provided' })
         .min(1, { error: 'vendor must not be empty' })
@@ -89,13 +96,6 @@ const CLISpecShape = z
             seen.add(p.key);
         }
     }),
-    connectionSlug: z
-        .string({ error: 'connectionSlug must be a string if provided' })
-        .min(1, { error: 'connectionSlug must not be empty if provided' })
-        .regex(CLI_ID_RE, {
-        error: (issue) => `invalid connectionSlug ${JSON.stringify(issue.input)}: lowercase letters/digits/hyphens/underscores only, must start with a letter`,
-    })
-        .optional(),
     vendorScopes: z
         .array(z.string({ error: 'vendorScopes[i] must be a string' }).min(1, { error: 'vendorScopes[i] must not be empty' }), { error: 'vendorScopes must be an array of strings if provided' })
         .optional(),
@@ -250,10 +250,10 @@ export function defineCLI(spec) {
         vendor: v.vendor ?? v.name,
         summary: v.summary,
         ...(v.description !== undefined ? { description: v.description } : {}),
+        ...(v.connectionSlug !== undefined ? { connectionSlug: v.connectionSlug } : {}),
         instructions: Object.freeze([...(v.instructions ?? [])]),
         secrets: frozenSecrets,
         properties: frozenProperties,
-        ...(v.connectionSlug !== undefined ? { connectionSlug: v.connectionSlug } : {}),
         ...(v.vendorScopes !== undefined ? { vendorScopes: Object.freeze([...v.vendorScopes]) } : {}),
         tools: Object.freeze(toolsMap),
     };

package/dist/define-connection.d.ts

@@ -0,0 +1,22 @@
+import type { ConnectionDef, ConnectionSpec } from './types.js';
+export declare function isAkaiConnection(x: unknown): x is ConnectionDef;
+/**
+ * Declare a connection: the umbrella identity that groups CLIs sharing one auth
+ * surface (e.g. `google` groups gmail + gsheet). Symmetric to `defineCLI` —
+ * returns a frozen, branded `ConnectionDef`.
+ *
+ * The manifest is the source of truth for IDENTITY (name/blurb/longDesc/
+ * instructions/vendor/authKind) and OAuth SHAPE (`oauth` block). It never holds
+ * the OAuth glue — client id/secret values, token storage, encryption, refresh
+ * hooks — nor UI cosmetics (hue/mark/logo). Those stay in akai-app, keyed by
+ * slug, a security boundary that never bakes into a per-tenant image.
+ *
+ * `defineConnection` is optional: a slug with no connection declaration is a
+ * single-CLI connection whose identity comes from its own `defineCLI` metadata.
+ * Declare one when ≥2 CLIs share a slug and need a single umbrella identity.
+ *
+ * CLIs link to a connection through `defineCLI({ connectionSlug: <slug> })` —
+ * `defineCLI` is unchanged.
+ */
+export declare function defineConnection(spec: ConnectionSpec): ConnectionDef;
+//# sourceMappingURL=define-connection.d.ts.map

package/dist/define-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-connection.d.ts","sourceRoot":"","sources":["../src/define-connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EAEb,cAAc,EAEf,MAAM,YAAY,CAAC;AAsJpB,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,aAAa,CAE/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CA4CpE"}

package/dist/define-connection.js

@@ -0,0 +1,201 @@
+import { z } from 'zod';
+import { AkaiConnectionError } from './errors.js';
+const SLUG_RE = /^[a-z][a-z0-9_-]*$/;
+const ADMIN_KEY_RE = /^[A-Z][A-Z0-9_]+$/;
+const OAUTH_KINDS = new Set(['oauth2']);
+const UrlString = z
+    .string({ error: 'must be a string' })
+    .min(1, { error: 'is required' })
+    .refine((val) => {
+    try {
+        new URL(val);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, { error: (issue) => `must be a valid URL (got ${JSON.stringify(issue.input)})` })
+    .refine((val) => {
+    try {
+        return new URL(val).protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}, { error: 'authorizeUrl/tokenUrl must be an https URL' });
+const OAuthAdminFieldShape = z.object({
+    key: z
+        .string({ error: 'key is required' })
+        .min(1, { error: 'key is required' })
+        .regex(ADMIN_KEY_RE, {
+        error: (issue) => `invalid key ${JSON.stringify(issue.input)}: env-style only ([A-Z][A-Z0-9_]+), e.g. GMAIL_CLIENT_ID`,
+    }),
+    label: z.string({ error: 'label is required' }).min(1, { error: 'label is required' }),
+    secret: z.boolean({ error: 'secret must be a boolean if provided' }).optional(),
+});
+const ConnectionOAuthConfigShape = z.object({
+    authorizeUrl: UrlString,
+    tokenUrl: UrlString,
+    scopes: z
+        .array(z.string({ error: 'scopes[i] must be a string' }).min(1, { error: 'scopes[i] must be non-empty' }), {
+        error: 'oauth.scopes must be an array of strings',
+    })
+        .min(1, { error: 'oauth.scopes must declare at least one scope' }),
+    pkce: z.boolean({ error: 'pkce must be a boolean if provided' }).optional(),
+    tokenEndpointAuthMethod: z
+        .enum(['client_secret_post', 'client_secret_basic'], {
+        error: 'tokenEndpointAuthMethod must be client_secret_post or client_secret_basic',
+    })
+        .optional(),
+    extraAuthorizeParams: z
+        .record(z.string(), z.string(), {
+        error: 'extraAuthorizeParams must be a string-to-string map if provided',
+    })
+        .optional(),
+    refreshStrategy: z
+        .enum(['cron', 'jit'], {
+        error: 'refreshStrategy must be cron or jit',
+    })
+        .optional(),
+    adminFields: z
+        .array(OAuthAdminFieldShape, { error: 'oauth.adminFields must be an array' })
+        .superRefine((fields, ctx) => {
+        const seen = new Set();
+        for (let i = 0; i < fields.length; i++) {
+            const f = fields[i];
+            if (seen.has(f.key)) {
+                ctx.addIssue({ code: 'custom', path: [i], message: `duplicate adminFields key: ${f.key}` });
+            }
+            seen.add(f.key);
+        }
+    }),
+    hasCustomConnectFlow: z.boolean({ error: 'hasCustomConnectFlow must be a boolean if provided' }).optional(),
+});
+const ConnectionSpecShape = z
+    .object({
+    slug: z
+        .string({ error: 'slug is required' })
+        .min(1, { error: 'slug is required' })
+        .regex(SLUG_RE, {
+        error: (issue) => `invalid slug ${JSON.stringify(issue.input)}: lowercase letters/digits/hyphens/underscores only, must start with a letter`,
+    }),
+    name: z.string({ error: 'name is required' }).min(1, { error: 'name is required' }),
+    vendor: z.string({ error: 'vendor is required' }).min(1, { error: 'vendor is required' }),
+    blurb: z.string({ error: 'blurb is required' }).min(1, { error: 'blurb is required' }),
+    longDesc: z.string({ error: 'longDesc is required' }).min(1, { error: 'longDesc is required' }),
+    instructions: z
+        .array(z.string({ error: 'instructions[i] must be a string' }), {
+        error: 'instructions must be an array of strings if provided',
+    })
+        .optional(),
+    authKind: z.enum(['apiKey', 'oauth2', 'none'], {
+        error: 'authKind must be one of apiKey, oauth2, none',
+    }),
+    oauth: ConnectionOAuthConfigShape.optional(),
+})
+    .superRefine((spec, ctx) => {
+    if (OAUTH_KINDS.has(spec.authKind)) {
+        if (!spec.oauth) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['oauth'],
+                message: `oauth is required when authKind is '${spec.authKind}'`,
+            });
+            return;
+        }
+        if (spec.oauth.adminFields.length < 1) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['oauth', 'adminFields'],
+                message: `oauth.adminFields must declare at least one field when authKind is '${spec.authKind}'`,
+            });
+        }
+    }
+    else if (spec.oauth !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['oauth'],
+            message: `oauth must not be set when authKind is '${spec.authKind}'`,
+        });
+    }
+});
+function throwSpecError(error) {
+    const issue = error.issues[0];
+    if (!issue)
+        throw new AkaiConnectionError('defineConnection: invalid spec');
+    const path = issue.path.length > 0 ? `${issue.path.join('.')} — ` : '';
+    throw new AkaiConnectionError(`defineConnection: ${path}${issue.message}`, {
+        path: issue.path,
+        issues: error.issues,
+    });
+}
+/**
+ * Connections registered by `defineConnection()`. `isAkaiConnection` uses this
+ * WeakSet so a hand-crafted `{ __akaiConnection: true, ... }` cannot pose as a
+ * connection to the registry loader. The brand on the object remains for
+ * human/debug visibility only.
+ */
+const CONNECTION_REGISTRY = new WeakSet();
+export function isAkaiConnection(x) {
+    return typeof x === 'object' && x !== null && CONNECTION_REGISTRY.has(x);
+}
+/**
+ * Declare a connection: the umbrella identity that groups CLIs sharing one auth
+ * surface (e.g. `google` groups gmail + gsheet). Symmetric to `defineCLI` —
+ * returns a frozen, branded `ConnectionDef`.
+ *
+ * The manifest is the source of truth for IDENTITY (name/blurb/longDesc/
+ * instructions/vendor/authKind) and OAuth SHAPE (`oauth` block). It never holds
+ * the OAuth glue — client id/secret values, token storage, encryption, refresh
+ * hooks — nor UI cosmetics (hue/mark/logo). Those stay in akai-app, keyed by
+ * slug, a security boundary that never bakes into a per-tenant image.
+ *
+ * `defineConnection` is optional: a slug with no connection declaration is a
+ * single-CLI connection whose identity comes from its own `defineCLI` metadata.
+ * Declare one when ≥2 CLIs share a slug and need a single umbrella identity.
+ *
+ * CLIs link to a connection through `defineCLI({ connectionSlug: <slug> })` —
+ * `defineCLI` is unchanged.
+ */
+export function defineConnection(spec) {
+    const parsed = ConnectionSpecShape.safeParse(spec);
+    if (!parsed.success)
+        throwSpecError(parsed.error);
+    // Build the def from the parsed (validated) snapshot, NOT from `spec` —
+    // re-reading `spec` after validation is TOCTOU-vulnerable to getter/proxy
+    // tricks that return different values on second read.
+    const v = parsed.data;
+    let oauth;
+    if (v.authKind === 'oauth2' && v.oauth) {
+        const adminFields = Object.freeze(v.oauth.adminFields.map((f) => Object.freeze({ ...f })));
+        oauth = Object.freeze({
+            authorizeUrl: v.oauth.authorizeUrl,
+            tokenUrl: v.oauth.tokenUrl,
+            scopes: Object.freeze([...v.oauth.scopes]),
+            ...(v.oauth.pkce !== undefined ? { pkce: v.oauth.pkce } : {}),
+            ...(v.oauth.tokenEndpointAuthMethod !== undefined
+                ? { tokenEndpointAuthMethod: v.oauth.tokenEndpointAuthMethod }
+                : {}),
+            ...(v.oauth.extraAuthorizeParams !== undefined
+                ? { extraAuthorizeParams: Object.freeze({ ...v.oauth.extraAuthorizeParams }) }
+                : {}),
+            ...(v.oauth.refreshStrategy !== undefined ? { refreshStrategy: v.oauth.refreshStrategy } : {}),
+            adminFields,
+            ...(v.oauth.hasCustomConnectFlow !== undefined ? { hasCustomConnectFlow: v.oauth.hasCustomConnectFlow } : {}),
+        });
+    }
+    const def = {
+        __akaiConnection: true,
+        slug: v.slug,
+        name: v.name,
+        vendor: v.vendor,
+        blurb: v.blurb,
+        longDesc: v.longDesc,
+        instructions: Object.freeze([...(v.instructions ?? [])]),
+        authKind: v.authKind,
+        ...(oauth !== undefined ? { oauth } : {}),
+    };
+    Object.freeze(def);
+    CONNECTION_REGISTRY.add(def);
+    return def;
+}

package/dist/errors.d.ts

@@ -10,6 +10,9 @@ export declare class AkaiError extends Error {
 /** Module-load-time spec error (bad call to `tool()` or `defineCLI()`). */
 export declare class AkaiSpecError extends AkaiError {
 }
+/** Module-load-time spec error from a bad call to `defineConnection()`. */
+export declare class AkaiConnectionError extends AkaiSpecError {
+}
 /** Input failed validation (zod parse, unknown flag, missing required arg). */
 export declare class AkaiInputError extends AkaiError {
 }
@@ -53,10 +56,12 @@ export type ToolErrorKind = 'not_found' | 'forbidden' | 'auth_expired' | 'invali
  * Caller-facing tool failure with a stable, vendor-neutral {@link ToolErrorKind}.
  *
  * Throw this from a tool handler when you want bespoke, author-vetted wording
- * for an expected failure. The host runtime brand-checks the thrown value by its
- * serialized shape — `{ name: 'AkaiToolError', kind, message, meta? }` — so the
- * `name` is pinned to `'AkaiToolError'` in the constructor and survives across
- * package-boundary `instanceof` gaps. On a match the host maps `kind` to an HTTP
+ * for an expected failure. The host runtime brand-checks the thrown value by
+ * property access on its shape — `{ name: 'AkaiToolError', kind, message, meta? }`
+ * (note `message` is read via property access, not JSON serialization, since
+ * `Error.message` is non-enumerable) — so the `name` is pinned to `'AkaiToolError'`
+ * in the constructor and survives across package-boundary `instanceof` gaps. On a
+ * match the host maps `kind` to an HTTP
  * status and returns `message` to the caller **verbatim**, so the message must be
  * secret-free and safe to expose. Untyped throws are classified generically.
  *

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAC5B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAK5D;AAED,2EAA2E;AAC3E,qBAAa,aAAc,SAAQ,SAAS;CAAG;AAE/C,+EAA+E;AAC/E,qBAAa,cAAe,SAAQ,SAAS;CAAG;AAEhD,8CAA8C;AAC9C,qBAAa,eAAgB,SAAQ,SAAS;CAAG;AAEjD,sDAAsD;AACtD,qBAAa,eAAgB,SAAQ,SAAS;CAAG;AAEjD,+DAA+D;AAC/D,qBAAa,iBAAkB,SAAQ,SAAS;CAAG;AAGnD,8EAA8E;AAC9E,qBAAa,aAAc,SAAQ,SAAS;CAAG;AAE/C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,WAAW,GACX,cAAc,GACd,eAAe,GACf,UAAU,GACV,cAAc,GACd,aAAa,CAAC;AAElB;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBACjB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAMhF,kGAAkG;IAClG,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAInF,4FAA4F;IAC5F,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAI/E,qFAAqF;IACrF,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAIhF,sFAAsF;IACtF,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAIlF,2EAA2E;IAC3E,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAI/E,kGAAkG;IAClG,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAIlF,oFAAoF;IACpF,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;CAGnF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAC5B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAK5D;AAED,2EAA2E;AAC3E,qBAAa,aAAc,SAAQ,SAAS;CAAG;AAE/C,2EAA2E;AAC3E,qBAAa,mBAAoB,SAAQ,aAAa;CAAG;AAEzD,+EAA+E;AAC/E,qBAAa,cAAe,SAAQ,SAAS;CAAG;AAEhD,8CAA8C;AAC9C,qBAAa,eAAgB,SAAQ,SAAS;CAAG;AAEjD,sDAAsD;AACtD,qBAAa,eAAgB,SAAQ,SAAS;CAAG;AAEjD,+DAA+D;AAC/D,qBAAa,iBAAkB,SAAQ,SAAS;CAAG;AAGnD,8EAA8E;AAC9E,qBAAa,aAAc,SAAQ,SAAS;CAAG;AAE/C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,WAAW,GACX,cAAc,GACd,eAAe,GACf,UAAU,GACV,cAAc,GACd,aAAa,CAAC;AAElB;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBACjB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAMhF,kGAAkG;IAClG,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAInF,4FAA4F;IAC5F,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAI/E,qFAAqF;IACrF,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAIhF,sFAAsF;IACtF,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAIlF,2EAA2E;IAC3E,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAI/E,kGAAkG;IAClG,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;IAIlF,oFAAoF;IACpF,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;CAGnF"}

package/dist/errors.js

@@ -14,6 +14,9 @@ export class AkaiError extends Error {
 /** Module-load-time spec error (bad call to `tool()` or `defineCLI()`). */
 export class AkaiSpecError extends AkaiError {
 }
+/** Module-load-time spec error from a bad call to `defineConnection()`. */
+export class AkaiConnectionError extends AkaiSpecError {
+}
 /** Input failed validation (zod parse, unknown flag, missing required arg). */
 export class AkaiInputError extends AkaiError {
 }
@@ -33,10 +36,12 @@ export class AkaiPathError extends AkaiError {
  * Caller-facing tool failure with a stable, vendor-neutral {@link ToolErrorKind}.
  *
  * Throw this from a tool handler when you want bespoke, author-vetted wording
- * for an expected failure. The host runtime brand-checks the thrown value by its
- * serialized shape — `{ name: 'AkaiToolError', kind, message, meta? }` — so the
- * `name` is pinned to `'AkaiToolError'` in the constructor and survives across
- * package-boundary `instanceof` gaps. On a match the host maps `kind` to an HTTP
+ * for an expected failure. The host runtime brand-checks the thrown value by
+ * property access on its shape — `{ name: 'AkaiToolError', kind, message, meta? }`
+ * (note `message` is read via property access, not JSON serialization, since
+ * `Error.message` is non-enumerable) — so the `name` is pinned to `'AkaiToolError'`
+ * in the constructor and survives across package-boundary `instanceof` gaps. On a
+ * match the host maps `kind` to an HTTP
  * status and returns `message` to the caller **verbatim**, so the message must be
  * secret-free and safe to expose. Untyped throws are classified generically.
  *

package/dist/index.d.ts

@@ -1,14 +1,15 @@
 export { tool, isAkaiTool, DYNAMIC_EGRESS_PREFIX } from './tool.js';
 export { defineCLI } from './define-cli.js';
 export { filePath, FILE_INPUT_META_KEY } from './file-input.js';
+export { defineConnection, isAkaiConnection } from './define-connection.js';
 export { buildScopedSecrets, buildScopedProperties } from './ctx/secrets.js';
 export type { SecretValues, PropertyValues } from './ctx/secrets.js';
 export { buildCtx } from './ctx/build-ctx.js';
 export type { BuildCtxParams } from './ctx/build-ctx.js';
-export type { AnyToolDef, CLIDef, CLISpec, DynamicEgress, InputOf, NetworkOptions, OutputOf, PropertiesOf, PropertyDecl, SecretDecl, SecretsOf, ToolCtx, ToolDef, ToolLogger, ToolOptions, ToolSpec, } from './types.js';
+export type { AnyToolDef, CLIDef, CLISpec, ConnectionAuthKind, ConnectionDef, ConnectionOAuthConfig, ConnectionSpec, DynamicEgress, InputOf, NetworkOptions, OAuthAdminField, OutputOf, PropertiesOf, PropertyDecl, RefreshStrategy, SecretDecl, SecretsOf, TokenEndpointAuthMethod, ToolCtx, ToolDef, ToolLogger, ToolOptions, ToolSpec, } from './types.js';
 export { createSafePath } from './ctx/safe-path.js';
 export type { SafePath } from './ctx/safe-path.js';
-export { AkaiEgressError, AkaiError, AkaiInputError, AkaiPathError, AkaiPropertyError, AkaiSecretError, AkaiSpecError, AkaiToolError, } from './errors.js';
+export { AkaiConnectionError, AkaiEgressError, AkaiError, AkaiInputError, AkaiPathError, AkaiPropertyError, AkaiSecretError, AkaiSpecError, AkaiToolError, } from './errors.js';
 export type { ToolErrorKind } from './errors.js';
 export { ConnectionManifestSchema, ManifestJSONSchema, SCHEMA_VERSION, toSchema, validateManifest, } from './manifest/index.js';
 export type { ConnectionManifest, DynamicEgressManifest, HttpToolManifest, ManifestProperty, ManifestSecret, NativeToolManifest, SchemaVersion, ToolManifest, } from './manifest/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EACV,UAAU,EACV,MAAM,EACN,OAAO,EACP,aAAa,EACb,OAAO,EACP,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,SAAS,EACT,OAAO,EACP,OAAO,EACP,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EACV,UAAU,EACV,MAAM,EACN,OAAO,EACP,kBAAkB,EAClB,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,OAAO,EACP,cAAc,EACd,eAAe,EACf,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,UAAU,EACV,SAAS,EACT,uBAAuB,EACvB,OAAO,EACP,OAAO,EACP,UAAU,EACV,WAAW,EACX,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,8 +1,9 @@
 export { tool, isAkaiTool, DYNAMIC_EGRESS_PREFIX } from './tool.js';
 export { defineCLI } from './define-cli.js';
 export { filePath, FILE_INPUT_META_KEY } from './file-input.js';
+export { defineConnection, isAkaiConnection } from './define-connection.js';
 export { buildScopedSecrets, buildScopedProperties } from './ctx/secrets.js';
 export { buildCtx } from './ctx/build-ctx.js';
 export { createSafePath } from './ctx/safe-path.js';
-export { AkaiEgressError, AkaiError, AkaiInputError, AkaiPathError, AkaiPropertyError, AkaiSecretError, AkaiSpecError, AkaiToolError, } from './errors.js';
+export { AkaiConnectionError, AkaiEgressError, AkaiError, AkaiInputError, AkaiPathError, AkaiPropertyError, AkaiSecretError, AkaiSpecError, AkaiToolError, } from './errors.js';
 export { ConnectionManifestSchema, ManifestJSONSchema, SCHEMA_VERSION, toSchema, validateManifest, } from './manifest/index.js';

package/dist/types.d.ts

@@ -122,6 +122,10 @@ export interface ToolCtx<S extends string = string, P extends string = string> {
      * but the host runtime did not supply the output staging dir.
      */
     writeFile: (name: string, data: Buffer | Uint8Array | string) => Promise<void>;
+    /** OAuth access token for this tool's connection, auto-wired by the host. */
+    oauth?: {
+        accessToken: string;
+    };
 }
 /** A built tool. Opaque to consumers, introspectable by the SDK. */
 export interface ToolDef<TInput = unknown, TOutput = unknown, TSecrets extends string = string, TProperties extends string = string> {
@@ -248,4 +252,139 @@ export interface CLISpec {
     vendorScopes?: readonly string[];
     tools: Record<string, AnyToolDef>;
 }
+/** The auth kind a connection declares — WHAT auth, never the glue. */
+export type ConnectionAuthKind = 'apiKey' | 'oauth2' | 'none';
+/** The token-endpoint client-auth method used on the OAuth code exchange. */
+export type TokenEndpointAuthMethod = 'client_secret_post' | 'client_secret_basic';
+/** How akai-app refreshes the access token once the connection is live. */
+export type RefreshStrategy = 'cron' | 'jit';
+/**
+ * One OAuth-app credential an admin must enter once per tenant (e.g. the OAuth
+ * client id / secret).
+ *
+ * This declares WHICH credential the admin supplies — the VALUE is entered in
+ * the akai-app UI and stored encrypted server-side, never in the manifest or
+ * the per-tenant image. `adminFields` are distinct from a CLI's `secrets[]`:
+ * `secrets[]` are user-facing access tokens / API keys; `adminFields` are the
+ * OAuth-app credentials set once by an admin (different lifecycle, storage, UI).
+ */
+export interface OAuthAdminField {
+    /**
+     * Env-style key the value is stored and looked up under, e.g.
+     * `GMAIL_CLIENT_ID`. Must match `[A-Z][A-Z0-9_]+` — it becomes a storage key
+     * in akai-app, so non-env-style keys are rejected at `defineConnection()`.
+     */
+    readonly key: string;
+    /** UI label for the input, e.g. `Client ID`. */
+    readonly label: string;
+    /**
+     * When `true`, akai-app masks the input in the admin form and redacts the
+     * value from logs. Default `false`. Set it for any credential that is itself
+     * a secret (client secret, signing key).
+     */
+    readonly secret?: boolean;
+}
+/**
+ * The OAuth shape a connection declares. akai-app reads this from the catalog,
+ * loads the `adminFields` values from its own DB at runtime, and runs the flow
+ * as a generic OAuth engine.
+ *
+ * The manifest declares SHAPE only. Client id/secret VALUES, token storage,
+ * encryption, and refresh hooks stay in akai-app — a security boundary, never
+ * baked into a per-tenant image.
+ */
+export interface ConnectionOAuthConfig {
+    /** OAuth authorize endpoint, e.g. `https://accounts.google.com/o/oauth2/v2/auth`. Must be a valid URL. */
+    readonly authorizeUrl: string;
+    /** OAuth token endpoint, e.g. `https://oauth2.googleapis.com/token`. Must be a valid URL. */
+    readonly tokenUrl: string;
+    /**
+     * The OAuth authorize scope set the connection requests, e.g. the Gmail /
+     * Drive / Sheets scope URIs. These are the connection-level handshake scopes
+     * the akai-app engine joins onto the authorize URL — distinct from a CLI's
+     * per-tool `vendorScopes`. Static per connection (dynamic scope-sets are out
+     * of scope); must declare at least one.
+     */
+    readonly scopes: readonly string[];
+    /** Use PKCE on the authorize/exchange. Default `false`. */
+    readonly pkce?: boolean;
+    /** Client-auth method on the token exchange. Default `client_secret_basic` (the akai-app engine default). */
+    readonly tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
+    /**
+     * Static extra query params appended to the authorize URL, e.g.
+     * `{ access_type: 'offline', prompt: 'consent' }`. A plain string map — dynamic
+     * (runtime-conditional) params are out of scope.
+     */
+    readonly extraAuthorizeParams?: Record<string, string>;
+    /**
+     * How akai-app keeps the token fresh. `cron` = a background job refreshes the
+     * token before it expires; `jit` = the token is refreshed just-in-time on the
+     * next use. These are the two values the akai-app engine branches on. Default
+     * `cron`.
+     */
+    readonly refreshStrategy?: RefreshStrategy;
+    /**
+     * The OAuth-app credentials an admin enters once per tenant. Min 1 (the client
+     * id; usually id + secret). Declares WHICH credentials are needed — the VALUES
+     * are stored encrypted in akai-app, never in the manifest/image.
+     */
+    readonly adminFields: readonly OAuthAdminField[];
+    /**
+     * When `true`, the connection uses a bespoke connect/disconnect flow instead
+     * of the generic akai-app OAuth routes (`/api/connections/[slug]/oauth/*`).
+     * akai-app uses this to suppress the generic Connect/Disconnect UI and skip
+     * the connection in `findOAuth2Connection`, deferring to the custom flow.
+     * Default `false`.
+     */
+    readonly hasCustomConnectFlow?: boolean;
+}
+/**
+ * Spec accepted by `defineConnection()`.
+ *
+ * A connection is the umbrella identity that groups CLIs sharing one auth
+ * surface (e.g. `google` groups gmail + gsheet). It declares the identity that
+ * surfaces on the Connections page and the auth kind — never the OAuth glue or
+ * UI cosmetics, which stay in akai-app keyed by slug.
+ */
+export interface ConnectionSpec {
+    /**
+     * Stable connection id. Groups every CLI that declares
+     * `defineCLI({ connectionSlug: <slug> })`. Same id-style rule as a CLI id:
+     * lowercase letters/digits/hyphens/underscores, must start with a letter.
+     */
+    slug: string;
+    /** Umbrella display name shown on the connection card and drawer, e.g. `Google Workspace`. */
+    name: string;
+    /** Vendor name, e.g. `Google`. */
+    vendor: string;
+    /** Short card text — one line on the Connections list. */
+    blurb: string;
+    /** Long-form drawer text shown when the connection is opened. */
+    longDesc: string;
+    /** Optional step-by-step setup notes rendered in the drawer. */
+    instructions?: readonly string[];
+    /**
+     * WHICH auth kind the connection uses. Declares WHAT auth, not the glue — the
+     * OAuth handshake (client creds, authorize/token URLs, refresh) stays in
+     * akai-app. When `oauth2`, `oauth` is required.
+     */
+    authKind: ConnectionAuthKind;
+    /**
+     * OAuth shape. Required when `authKind` is `oauth2`; ignored otherwise.
+     * Declares the shape only — secret VALUES live in akai-app.
+     */
+    oauth?: ConnectionOAuthConfig;
+}
+/** A built connection. Opaque to consumers, introspectable by the SDK. Mirrors `CLIDef`. */
+export interface ConnectionDef {
+    readonly __akaiConnection: true;
+    readonly slug: string;
+    readonly name: string;
+    readonly vendor: string;
+    readonly blurb: string;
+    readonly longDesc: string;
+    readonly instructions: ReadonlyArray<string>;
+    readonly authKind: ConnectionAuthKind;
+    readonly oauth?: ConnectionOAuthConfig;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akai-workflow-builder/cli-sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Authoring SDK for atomic, agent-executable CLIs and tools.",
   "keywords": [
     "akai",