@keemakr/operator-sdk 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/operator-sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The keemakr connector contract: defineProvider + ConnectionProvider/ConnectionOperation types + OperationContext (governed fetch) + the connector manifest schema, shared by keemakr-core's built-in adapters and external connector repos. One shape, two consumers.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -136,11 +136,12 @@ export interface OperationContext {
   actor?: Readonly<OperationActor>;
 }
 
-// Slim context for the OAuth lifecycle hooks (buildAuthUrl/exchangeCode/refresh):
-// connector-level config, plus the governed fetch for the token exchange —
-// marketplace connector code may not touch ambient fetch ANYWHERE (the publish
-// scan bans it), so the lifecycle's egress rides the same fenced client as
-// operations. There is no tenant credential yet at these steps.
+// Slim context for the lifecycle hooks (buildAuthUrl/exchangeCode/refresh, and
+// extractMeta at connect time): connector-level config, plus the governed fetch
+// for the token exchange and any connect-time lookup — marketplace connector
+// code may not touch ambient fetch ANYWHERE (the publish scan bans it), so the
+// lifecycle's egress rides the same fenced client as operations. There is no
+// stored tenant credential yet at these steps.
 export interface LifecycleContext {
   config?: Record<string, string>;
   fetch?: typeof fetch;
@@ -287,9 +288,15 @@ export interface ConnectionProvider {
   ): Promise<TestResult>;
 
   // Derive a human-readable account_label + durable handle
-  // (stripe_user_id, store url, ...) to persist alongside the token.
+  // (stripe_user_id, store url, ad account id, ...) to persist alongside the
+  // token. Runs once per connect, right after exchangeCode (oauth2) or test()
+  // (api_key / app_password). `ctx` is the same lifecycle context the connect
+  // step used: look the account up with `ctx.fetch` (the governed client,
+  // fenced to your `allowed_domains`), never ambient fetch. Optional in the type
+  // so one-argument implementations compile unchanged.
   extractMeta?(
     token: TokenSet,
+    ctx?: LifecycleContext,
   ): Promise<{ accountLabel: string | null; meta: Record<string, unknown> }>;
 
   // Named proxy operations a marketplace agent may invoke through the Capability
@@ -382,7 +389,11 @@ export type ProviderDefinition<Ops extends Record<string, OperationInputSchema>>
 // broken connector, and an auth failure must revoke, not retry.
 //   provider_unavailable → the upstream API is down/5xx/timing out
 //   connector_error      → the connector's own fault (bug, bad normalization)
-//   auth_revoked         → the credential is dead (401-class, invalid_grant)
+//   auth_revoked         → the credential is dead (401-class). From refresh(),
+//                          it revokes only alongside the token endpoint's
+//                          `invalid_grant` (keep the word in the message);
+//                          without it core degrades instead, since a 401 there
+//                          can be the connector's own client credentials.
 //   egress_blocked       → the governed fetch refused a non-allowlisted host
 //   rate_limited         → upstream 429 (platform applies backoff)
 export type OperationErrorCode =

package/src/manifest.ts

@@ -129,6 +129,119 @@ export const connectorOperationDeclaration = z.object({
   input_schema: operationInputJsonSchema.optional(),
 });
 
+// A name inside a push scheme's envelope (`page`, `leadgen`): lowercase, underscores allowed.
+const pushName = /^[a-z][a-z0-9_]{0,63}$/;
+
+/** The op that subscribes (or unsubscribes) an account at the provider, and the arg naming it. */
+const pushAccountOp = z.object({
+  op: z.string().regex(opName, 'operation names are lowercase, dot/hyphen-scoped'),
+  account_ref_arg: z.string().min(1).max(100),
+});
+
+/**
+ * PUSHED UPDATES: the provider calls core when something happens, instead of core asking. Core
+ * owns the door (`/api/webhooks/connections/<provider>`): it checks the provider's signature with
+ * the connector's own config secret, finds the workspaces from the account the update names, and
+ * hands each one to the installs that depend on this connector as `core.connection_event.received`.
+ *
+ * `scheme` is the provider's protocol, implemented once in core. `websub_graph` is the WebSub
+ * verification handshake (`hub.challenge`) plus an `X-Hub-Signature-256` HMAC of the raw body and
+ * the `{ object, entry: [{ id, changes: [{ field, value }] }] }` envelope.
+ *
+ * `fields` is the REVIEWED allowlist of what may come through: an update whose (object, field) is
+ * not listed is dropped at the door. What a listed field carries reaches a handler under the
+ * install's full grant, so a reviewer judges it here, at publish.
+ *
+ * `register` names the operation that subscribes an account at the provider and the argument that
+ * holds the account's id. When that operation runs, core first notes the account for the calling
+ * workspace as pending (a call core cannot note is refused), and turns it on only when the provider
+ * accepts: only accepted accounts are delivered, so naming an account the workspace's credential
+ * does not manage reaches nothing. `unregister`, when the connector has an operation to unsubscribe,
+ * turns the account off once the provider accepts. The secret and the verify token must be
+ * different keys: the token travels in the clear during the provider's handshake.
+ *
+ * OPTIONAL, and it must stay optional: stored manifests are re-parsed at every publish.
+ */
+export const connectorPushDeclaration = z
+  .object({
+    scheme: z.enum(['websub_graph']),
+    secret_key: z.string().regex(/^[A-Z][A-Z0-9_]*$/, 'config keys are SCREAMING_SNAKE'),
+    verify_token_key: z.string().regex(/^[A-Z][A-Z0-9_]*$/, 'config keys are SCREAMING_SNAKE'),
+    fields: z
+      .array(
+        z.object({
+          object: z.string().regex(pushName, 'push objects are lowercase, underscores allowed'),
+          field: z.string().regex(pushName, 'push fields are lowercase, underscores allowed'),
+        }),
+      )
+      .min(1, 'declare at least one (object, field) the provider may push')
+      .max(50),
+    register: pushAccountOp,
+    unregister: pushAccountOp.optional(),
+  })
+  .superRefine((p, ctx) => {
+    // The verify token is sent in the clear (a URL query) during the provider's handshake; the secret
+    // signs every delivery for every customer. One key for both would put the secret in access logs.
+    if (p.secret_key === p.verify_token_key) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['verify_token_key'],
+        message: 'verify_token_key must be a different config key from secret_key',
+      });
+    }
+    if (p.unregister && p.unregister.op === p.register.op) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['unregister', 'op'],
+        message: 'push.unregister.op must differ from push.register.op',
+      });
+    }
+    const seen = new Set<string>();
+    for (const [i, f] of p.fields.entries()) {
+      const k = `${f.object}.${f.field}`;
+      if (seen.has(k)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['fields', i],
+          message: `push.fields lists '${k}' twice`,
+        });
+      }
+      seen.add(k);
+    }
+  });
+
+/**
+ * What a push declaration must agree on with the rest of its manifest: the secret and the verify
+ * token are declared config keys (staff can only set a declared key), and the register and
+ * unregister operations are declared operations. Paths are relative to `push`. Pure. Core runs it
+ * again when it reads a pinned manifest, so a block that no longer agrees opens no door.
+ */
+export function pushCrossCheckIssues(
+  push: ConnectorPushDeclaration,
+  manifest: { env: readonly string[]; operations: ReadonlyArray<{ name: string }> },
+): Array<{ path: (string | number)[]; message: string }> {
+  const out: Array<{ path: (string | number)[]; message: string }> = [];
+  for (const key of ['secret_key', 'verify_token_key'] as const) {
+    if (!manifest.env.includes(push[key])) {
+      out.push({
+        path: [key],
+        message: `push.${key} '${push[key]}' must be one of the config keys declared in env`,
+      });
+    }
+  }
+  const ops = new Set(manifest.operations.map((o) => o.name));
+  for (const which of ['register', 'unregister'] as const) {
+    const decl = push[which];
+    if (decl && !ops.has(decl.op)) {
+      out.push({
+        path: [which, 'op'],
+        message: `push.${which}.op '${decl.op}' is not one of the declared operations`,
+      });
+    }
+  }
+  return out;
+}
+
 export const connectorManifestSchema = z
   .object({
     kind: z.literal('connection'),
@@ -220,6 +333,8 @@ export const connectorManifestSchema = z
     // the publish gate (both directions: no undeclared ops, no phantom ops). For
     // remote connectors this list IS the contract core builds the forwarder from.
     operations: z.array(connectorOperationDeclaration).min(1),
+    // Updates the provider pushes to core (see connectorPushDeclaration). Optional.
+    push: connectorPushDeclaration.optional(),
     changelog: z.string().max(5000).optional(),
   })
   .superRefine((m, ctx) => {
@@ -276,11 +391,17 @@ export const connectorManifestSchema = z
           'mcp connectors must declare connect_fields (there is no adapter code to own the form)',
       });
     }
+    if (m.push) {
+      for (const issue of pushCrossCheckIssues(m.push, m)) {
+        ctx.addIssue({ code: 'custom', path: ['push', ...issue.path], message: issue.message });
+      }
+    }
   });
 
 export type ConnectorOperationDeclaration = z.infer<typeof connectorOperationDeclaration>;
 export type OperationInputJsonSchema = z.infer<typeof operationInputJsonSchema>;
 export type ConnectorManifest = z.infer<typeof connectorManifestSchema>;
+export type ConnectorPushDeclaration = z.infer<typeof connectorPushDeclaration>;
 
 // Parse + normalize an entry.json object. Throws ZodError on invalid input;
 // callers wanting a report use connectorManifestSchema.safeParse directly.