@keemakr/operator-sdk 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/operator-sdk",
-  "version": "0.3.0",
+  "version": "0.5.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/conformance/index.ts

@@ -68,6 +68,15 @@ export async function runConformance(
     !manifest.auth_kind || provider.authKind === manifest.auth_kind,
     `code '${provider.authKind}' vs manifest '${manifest.auth_kind ?? '—'}'`,
   );
+  // The credential alias is a reviewed dependency: when either side declares
+  // it, both must, and they must agree (a code-only alias would ride a
+  // connection reviewers never saw).
+  add(
+    'credential-alias',
+    'credential alias matches the manifest (when either declares it)',
+    (provider.credentialProvider ?? null) === (manifest.credential_provider ?? null),
+    `code '${provider.credentialProvider ?? '—'}' vs manifest '${manifest.credential_provider ?? '—'}'`,
+  );
 
   // 6 — code may not claim MORE network than the reviewed manifest.
   const undeclared = (provider.allowedDomains ?? []).filter(

package/src/index.ts

@@ -100,6 +100,24 @@ export interface ConnectField {
   help?: string;
 }
 
+// Outcome of a connect-time (or on-demand) health probe. `status` is the user-
+// facing vocabulary the Hub renders: 'connected' (probe passed), 'needs_rescope'
+// (OAuth completed but the granted scopes can't run this provider's operations —
+// e.g. Google's granular-consent checkboxes were left unticked), 'no_mailbox'
+// (the account exists but has no mailbox/service behind it — a Workspace account
+// on a Microsoft-mail domain), 'unusable' (probe failed for another reason).
+export interface ProbeResult {
+  status: 'connected' | 'needs_rescope' | 'no_mailbox' | 'unusable';
+  /** One human-readable sentence for the Hub's status chip. */
+  detail?: string;
+  /** Scopes the credential actually carries, when the probe can read them. */
+  grantedScopes?: string[];
+  /** Probed account identity (e.g. the mailbox email) — becomes account_label. */
+  accountLabel?: string | null;
+  /** Extra provider facts worth persisting under meta.probe. */
+  meta?: Record<string, unknown>;
+}
+
 export interface ConnectionProvider {
   provider: string;
   displayName: string;
@@ -112,6 +130,29 @@ export interface ConnectionProvider {
   // Connect-path maturity. Omitted ⇒ 'ready'. See Maturity above.
   maturity?: Maturity;
 
+  // NOTE: a connection's scope (personal 'user' vs org-shared 'tenant') is NOT
+  // declared on the adapter. The live value is connections_registry.connection_mode
+  // (the platform-controlled overlay + rollback lever). Marketplace connectors
+  // seed it by declaring `connection_mode` in the MANIFEST (first publish only —
+  // the registry column is authoritative afterward, and reclassifying a live
+  // provider is a guarded staff console action). Built-ins still seed from
+  // registry-state's DEFAULT_USER_MODE_PROVIDERS, which stays the fail-closed
+  // fallback for unreadable registry reads.
+
+  // OAuth scopes this provider's operations actually NEED — unlike `scopes`
+  // (display-only), these are compared against the granted scope string by the
+  // connect-time probe; missing entries mark the connection 'needs_rescope'.
+  requiredScopes?: string[];
+
+  // Connect-time health probe: one cheap read (a profile fetch) that proves the
+  // credential can actually operate, run after the OAuth reports success and on
+  // demand from the Hub's "Check connection". Omitted ⇒ the connection is
+  // trusted as-is (status stays whatever the OAuth layer reported).
+  probe?(
+    cred: { accessToken: string; meta: Record<string, unknown> },
+    ctx?: OperationContext,
+  ): Promise<ProbeResult>;
+
   // Audience classification — see ConnectorSurface. Drives whether the end-user
   // client surfaces this connector and how. Optional in the type for now so
   // existing/external adapters compile through the SDK bump; defineProvider warns
@@ -130,6 +171,17 @@ export interface ConnectionProvider {
   // omit it (first-party).
   publisher?: string;
 
+  // Credential alias — the agent-tool chain's "one key opens many doors" seam.
+  // A connector that fronts one facet of a wider platform (an Apify actor, a
+  // Composio toolkit) declares the provider whose TENANT CONNECTION it rides:
+  // when a tenant has no row for THIS provider, getConnection falls back to the
+  // alias provider's row (tenant connects 'apify' once; every actor connector
+  // works). A tenant-pasted key for this provider still wins — the alias is the
+  // fallback, not the override. Refresh semantics follow the ALIAS provider's
+  // adapter. One hop only; the alias must name a concrete provider, never
+  // another aliased one.
+  credentialProvider?: string;
+
   // 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
@@ -193,6 +245,9 @@ export interface ConnectionProvider {
 // sees it. Keep `call` pure-ish: do the request, return JSON-serializable data.
 export interface ConnectionOperation {
   description?: string;
+  // Platform-only provider primitive. It remains available to trusted internal callers that
+  // invoke the adapter directly, but is omitted from catalogs and agent/user operation surfaces.
+  internal?: boolean;
   // Access class, for grant scoping + install consent. Omitted ⇒ 'write' (the
   // most restrictive assumption: unlabeled ops require the write scope and are
   // listed as writes on the consent screen).

package/src/manifest.ts

@@ -46,6 +46,19 @@ export const connectorManifestSchema = z
     // publish gate. Optional (the adapter is authoritative); declaring it lets
     // the upload preview show it before any code runs.
     auth_kind: z.enum(['oauth2', 'api_key', 'app_password']).optional(),
+    // OWNERSHIP axis (orthogonal to `surface`): 'user' = each member connects
+    // their OWN account (one row per member, invisible to everyone else — a
+    // personal mailbox/drive/calendar); 'tenant' = one org-shared connection.
+    // Declare 'user' whenever the credential is one person's own account.
+    //
+    // Contract: this value SEEDS connections_registry.connection_mode at FIRST
+    // publish only — the platform column is authoritative afterward. Changing
+    // it in a later version raises a publish-diff warning and does NOT apply;
+    // live reclassification is a guarded staff console action (adopt/clean-cut).
+    // NEVER make this required, and never make the schema strict: stored
+    // manifests of already-published versions are re-parsed with the current
+    // schema at every publish, and only a defaulted optional field survives that.
+    connection_mode: z.enum(['tenant', 'user']).default('tenant'),
     // The operator-sdk contract version the connector targets (semver).
     sdk_version: z.string().regex(/^\d+\.\d+\.\d+$/, 'sdk_version must be exact semver'),
     // Module (relative path inside the bundle) whose named export is the
@@ -92,6 +105,14 @@ export const connectorManifestSchema = z
     allowed_domains: z
       .array(z.string().regex(domainPattern, 'each entry is a bare host or *.host, optional :port'))
       .min(1, 'declare at least one allowed domain'),
+    // Credential alias (see ConnectionProvider.credentialProvider): the provider
+    // whose tenant connection this connector rides when the tenant has not
+    // connected THIS provider directly. Declared here so reviewers see the
+    // dependency; the adapter's copy is authoritative at runtime.
+    credential_provider: z
+      .string()
+      .regex(kebab, 'credential_provider must be a lowercase-kebab provider key')
+      .optional(),
     // Connector-level config keys the platform must supply (resolved from the
     // encrypted config store — values are set by staff at publish, never bundled).
     env: z