@keemakr/operator-sdk 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/operator-sdk",
-  "version": "0.4.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/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
@@ -204,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