@keemakr/operator-sdk 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@keemakr/operator-sdk",
+  "version": "0.1.0",
+  "description": "The keemakr connector contract: defineProvider + ConnectionProvider/ConnectionOperation types, shared by keemakr-core's built-in adapters and external connector repos. One shape, two consumers.",
+  "type": "module",
+  "license": "MIT",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "zod": "^4.4.3"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fsztpartners/keemakr.git",
+    "directory": "packages/operator-sdk"
+  }
+}

package/src/index.ts

@@ -0,0 +1,173 @@
+// @keemakr/operator-sdk — the connector contract.
+//
+// The canonical home of the ConnectionProvider seam. keemakr-core's built-in
+// adapters and external connector repos import the exact same symbols from this
+// package. One shape, one validator, two consumers.
+//
+// Each connectable provider ships one adapter implementing ConnectionProvider.
+// The adapter is the source of truth for the provider's metadata (synced into
+// connections_registry) and for its auth lifecycle (build auth URL, exchange
+// code, refresh, validate a credential, derive an account label).
+
+export type AuthKind = 'oauth2' | 'api_key' | 'app_password';
+
+// How proven the adapter's connect path is.
+//   'ready'       → the connect + validate path is tested and works; the user
+//                   only needs to supply their own API key/credential.
+//   'coming_soon' → code-complete but the live connect round-trip is NOT proven
+//                   (OAuth-broker providers without a test app, token-paste
+//                   stand-ins for a not-yet-wired OAuth flow, …). The UI badges
+//                   these "Coming soon" and disables Connect.
+// Omitted on an adapter ⇒ treated as 'ready' (the registry column also defaults
+// to 'ready'), so legacy adapters stay connectable until told otherwise.
+export type Maturity = 'ready' | 'coming_soon';
+
+export interface TokenSet {
+  accessToken: string;
+  refreshToken?: string | null;
+  scope?: string | null;
+  expiresAt?: string | null; // ISO 8601
+  meta?: Record<string, unknown>;
+}
+
+export interface TestResult {
+  ok: boolean;
+  detail?: string;
+}
+
+// A single field in an inline connect form (api_key / app_password adapters).
+// The UI renders these generically; the adapter owns the spec so the form and
+// the route's expectations never drift. `target` says where the value goes in
+// the POST body:
+//   'access_token'        → body.access_token (e.g. PostHog project key)
+//   'username'            → body.username (self-hosted WordPress)
+//   'application_password'→ body.application_password (self-hosted WordPress)
+//   'meta.<key>'          → body.meta[<key>] (e.g. meta.host, meta.site_url)
+export interface ConnectField {
+  target: string;
+  label: string;
+  placeholder?: string;
+  secret?: boolean; // render as type=password
+  optional?: boolean;
+  help?: string;
+}
+
+export interface ConnectionProvider {
+  provider: string;
+  displayName: string;
+  authKind: AuthKind;
+  category?: string;
+  scopes?: string[];
+  icon?: string;
+  docUrl?: string;
+  enabled?: boolean;
+  // Connect-path maturity. Omitted ⇒ 'ready'. See Maturity above.
+  maturity?: Maturity;
+
+  // Inline connect-form spec for api_key / app_password shapes. Omitted by pure
+  // oauth2 adapters (they render a Connect button instead). For a dual-mode
+  // provider (WordPress), this describes the NON-oauth fallback form; the UI
+  // also offers the oauth2 button.
+  //
+  // This is the SINGLE source of truth for the connect form — the UI fetches it
+  // from the catalog (GET /api/connections), so there is no second place to
+  // declare fields. Add a field here and it renders; nothing else to touch.
+  connectFields?: ConnectField[];
+
+  // Dual-mode = authKind:'oauth2' as the PRIMARY shape, but ALSO offers the
+  // connectFields form as a fallback (WordPress: .com OAuth OR self-hosted
+  // app-password). When true, the connect panel renders both the OAuth button
+  // AND the inline form. A form posted for a dual-mode provider carries
+  // meta.mode='<fallbackMode>' so the route/adapter know which branch to take.
+  dualMode?: { fallbackMode: string; oauthLabel?: string; formLabel?: string };
+
+  // OAuth-only lifecycle. Omitted by api_key / app_password adapters.
+  buildAuthUrl?(args: { tenantId: string; state: string; callbackUrl: string }): string;
+  exchangeCode?(args: { code: string; callbackUrl: string }): Promise<TokenSet>;
+  refresh?(args: { refreshToken: string }): Promise<TokenSet>;
+
+  // All kinds — validate a credential at save time.
+  test(args: { accessToken: string; meta: Record<string, unknown> }): Promise<TestResult>;
+
+  // Derive a human-readable account_label + durable handle
+  // (stripe_user_id, store url, ...) to persist alongside the token.
+  extractMeta?(
+    token: TokenSet,
+  ): Promise<{ accountLabel: string | null; meta: Record<string, unknown> }>;
+
+  // Named proxy operations a marketplace agent may invoke through the Capability
+  // API (L11). Co-located with the credential logic here so the platform owns
+  // them; agents call by name and never see the credential. Each operation:
+  //   inputSchema  validates the args the agent sends (zod or JSON-schema-ish);
+  //   call(cred, args)  runs the third-party request SERVER-SIDE with the
+  //                     resolved credential and returns the RESULT (never the
+  //                     credential). Throw OperationError for a typed failure.
+  // Omitted ⇒ the provider exposes no proxy operations (proxy calls 404).
+  operations?: Record<string, ConnectionOperation>;
+}
+
+// One named, credential-backed proxy operation. `cred` is the resolved
+// connection (access token + meta); the platform passes it in — the agent never
+// sees it. Keep `call` pure-ish: do the request, return JSON-serializable data.
+export interface ConnectionOperation {
+  description?: string;
+  // A Standard Schema (zod/valibot/…) validating the agent-supplied args. Typed
+  // loosely here so the connector contract doesn't hard-depend on zod; adapters
+  // pass a zod schema and the route validates with `.parse`/`.safeParse`.
+  inputSchema: {
+    safeParse(input: unknown): { success: boolean; data?: unknown; error?: unknown };
+  };
+  call(
+    cred: { accessToken: string; meta: Record<string, unknown> },
+    args: Record<string, unknown>,
+  ): Promise<unknown>;
+}
+
+// Throw from a ConnectionOperation.call to surface a typed, agent-safe failure
+// (maps to a 4xx with a clean message — never leaks the credential).
+export class OperationError extends Error {
+  status: number;
+  constructor(message: string, status = 400) {
+    super(message);
+    this.name = 'OperationError';
+    this.status = status;
+  }
+}
+
+// ─── Authoring helper ────────────────────────────────────────────────────────
+//
+// Define a provider adapter with this instead of a bare object literal. It is an
+// identity function (returns its argument unchanged) whose only job is to give
+// you full TypeScript checking + editor autocomplete on the ConnectionProvider
+// shape, and to fail fast on a few mistakes the type system can't catch:
+//
+//   - a non-oauth2 adapter that forgot connectFields (its form would be a single
+//     bare "API key" box — usually a bug)
+//   - an oauth2 adapter missing buildAuthUrl/exchangeCode (its Connect button
+//     would 500 at the broker)
+//   - a provider key that isn't lowercase-kebab (must match the URL segment and
+//     the connections_registry row)
+//
+// Usage: see keemakr-core's lib/connections/providers/_template.ts.
+export function defineProvider(p: ConnectionProvider): ConnectionProvider {
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(p.provider)) {
+    throw new Error(
+      `connections: provider key '${p.provider}' must be lowercase-kebab (e.g. 'mailchimp', 'google-ads')`,
+    );
+  }
+  if (p.authKind === 'oauth2') {
+    if (typeof p.buildAuthUrl !== 'function' || typeof p.exchangeCode !== 'function') {
+      throw new Error(
+        `connections: oauth2 provider '${p.provider}' must implement buildAuthUrl() and exchangeCode()`,
+      );
+    }
+  } else if (!p.connectFields || p.connectFields.length === 0) {
+    throw new Error(
+      `connections: ${p.authKind} provider '${p.provider}' must declare connectFields (the inline connect form)`,
+    );
+  }
+  if (typeof p.test !== 'function') {
+    throw new Error(`connections: provider '${p.provider}' must implement test()`);
+  }
+  return p;
+}