@stigmer/sdk 3.14.0 → 3.15.0

package/src/ensure-identity-account.ts

@@ -0,0 +1,87 @@
+/**
+ * The first-sign-in flow, once: make sure the authenticated caller has an
+ * identity account, creating it if this is the first time they arrive.
+ *
+ * Every edition serves `IdentityAccount` from one controller (20260911.11),
+ * and every surface that greets a signed-in person runs the same two-step
+ * flow — the console's `useIdentityAccountGate` (`@stigmer/react`), the
+ * CLI's `auth login` and `auth whoami`, and any platform builder's own
+ * gate. This module is that flow's one home, so the surfaces cannot drift
+ * on the question "what does a missing account mean?".
+ *
+ * Three facts it is built on:
+ *
+ * - `whoAmI` answers NOT_FOUND for an authenticated caller who has no
+ *   account yet (the server's byte-pinned copy: "Identity account not found
+ *   for the authenticated user"). That code, and ONLY that code, means
+ *   "provision me". UNAUTHENTICATED, UNAVAILABLE, a transport fault — each
+ *   is the caller's to handle and is rethrown as the same object.
+ * - `provisionMyAccount` is the one creator of a direct account and is
+ *   idempotent by the caller's subject: two racing first sign-ins resolve
+ *   to one row. Its failures are also rethrown untouched (the issuer's
+ *   userinfo being down is UNAVAILABLE, the documented arm).
+ * - Whether THIS call created the account is part of the answer. A first
+ *   sign-in should be visible ("your account was created"), not silent.
+ *
+ * The client parameter is structural, the `McpServerConnectLane` precedent:
+ * the full `Stigmer` client satisfies it, and a test can hand in two
+ * functions.
+ */
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { isNotFound } from "./errors.js";
+
+/**
+ * The slice of the identity-account client this flow needs. Errors are the
+ * SDK client's `StigmerError`s; `isNotFound` is the one classifier read.
+ */
+export interface IdentityAccountLane {
+  whoAmI(): Promise<IdentityAccount>;
+  provisionMyAccount(): Promise<IdentityAccount>;
+}
+
+/** Options for {@link ensureMyIdentityAccount}. */
+export interface EnsureMyIdentityAccountOptions {
+  /**
+   * Called once, before `provisionMyAccount` is issued, when `whoAmI` found
+   * no account — the moment a surface shows "Setting up your account…".
+   * Not called when the account already exists.
+   */
+  readonly onProvisioning?: () => void;
+}
+
+/** What {@link ensureMyIdentityAccount} learned. */
+export interface EnsuredIdentityAccount {
+  /** The caller's account, existing or just created. */
+  readonly account: IdentityAccount;
+  /** `true` when this call created the account (a first sign-in). */
+  readonly created: boolean;
+}
+
+/**
+ * Resolve the caller's identity account, provisioning it on a first sign-in.
+ *
+ * `whoAmI` first; on NOT_FOUND — and only NOT_FOUND — `onProvisioning` fires
+ * and `provisionMyAccount` runs. Every other error, from either RPC, is
+ * rethrown as the same object so the caller's error UX owns it.
+ *
+ * @example
+ * ```ts
+ * const { account, created } = await ensureMyIdentityAccount(stigmer, {
+ *   onProvisioning: () => console.log("Setting up your account…"),
+ * });
+ * ```
+ */
+export async function ensureMyIdentityAccount(
+  client: { readonly identityAccount: IdentityAccountLane },
+  options?: EnsureMyIdentityAccountOptions,
+): Promise<EnsuredIdentityAccount> {
+  try {
+    const account = await client.identityAccount.whoAmI();
+    return { account, created: false };
+  } catch (err: unknown) {
+    if (!isNotFound(err)) throw err;
+  }
+  options?.onProvisioning?.();
+  const account = await client.identityAccount.provisionMyAccount();
+  return { account, created: true };
+}

package/src/gen/resource-availability.ts

@@ -1,20 +1,43 @@
 // Code generated by stigmer-codegen from api_resource_kind.proto kind_meta. DO NOT EDIT.
 
-import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceKind, ResourceTier } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 
 /**
- * Resource kinds whose proto kind_meta.tier is cloud_only.
+ * The minimum edition that serves each resource kind (kind_meta.tier).
+ *
+ * Every kind with kind_meta is present, in enum-number order; a kind
+ * absent here has no tier and is a programming error to ask about.
  *
  * Source of truth: api_resource_kind.proto — each ApiResourceKind enum
  * value carries a ResourceTier in its kind_meta options.
  */
-export const CLOUD_ONLY_KINDS: ReadonlySet<ApiResourceKind> = new Set([
-  ApiResourceKind.api_resource_version,
-  ApiResourceKind.iam_policy,
-  ApiResourceKind.identity_account,
-  ApiResourceKind.invitation,
-  ApiResourceKind.identity_provider,
-  ApiResourceKind.oauth_app,
-  ApiResourceKind.platform_client,
-  ApiResourceKind.platform,
+export const KIND_TIERS: ReadonlyMap<ApiResourceKind, ResourceTier> = new Map([
+  [ApiResourceKind.api_resource_version, ResourceTier.cloud_only],
+  [ApiResourceKind.iam_policy, ResourceTier.enterprise],
+  [ApiResourceKind.identity_account, ResourceTier.open_source],
+  [ApiResourceKind.api_key, ResourceTier.open_source],
+  [ApiResourceKind.invitation, ResourceTier.enterprise],
+  [ApiResourceKind.identity_provider, ResourceTier.enterprise],
+  [ApiResourceKind.oauth_app, ResourceTier.open_source],
+  [ApiResourceKind.platform_client, ResourceTier.cloud_only],
+  [ApiResourceKind.organization, ResourceTier.open_source],
+  [ApiResourceKind.platform, ResourceTier.enterprise],
+  [ApiResourceKind.agent, ResourceTier.open_source],
+  [ApiResourceKind.agent_execution, ResourceTier.open_source],
+  [ApiResourceKind.session, ResourceTier.open_source],
+  [ApiResourceKind.skill, ResourceTier.open_source],
+  [ApiResourceKind.mcp_server, ResourceTier.open_source],
+  [ApiResourceKind.agent_instance, ResourceTier.open_source],
+  [ApiResourceKind.agent_share, ResourceTier.open_source],
+  [ApiResourceKind.agent_channel, ResourceTier.open_source],
+  [ApiResourceKind.channel_app, ResourceTier.open_source],
+  [ApiResourceKind.workflow, ResourceTier.open_source],
+  [ApiResourceKind.workflow_instance, ResourceTier.open_source],
+  [ApiResourceKind.workflow_execution, ResourceTier.open_source],
+  [ApiResourceKind.environment, ResourceTier.open_source],
+  [ApiResourceKind.execution_context, ResourceTier.open_source],
+  [ApiResourceKind.artifact, ResourceTier.open_source],
+  [ApiResourceKind.schedule, ResourceTier.open_source],
+  [ApiResourceKind.memory, ResourceTier.open_source],
+  [ApiResourceKind.project, ResourceTier.open_source],
 ]);

package/src/index.ts

@@ -55,12 +55,23 @@ export {
   getRpcMetadata,
 } from "./errors.js";
 
-// Resource availability
+// Edition vocabulary and resource availability
 export {
   type DeploymentMode,
+  deploymentModeOf,
   isResourceAvailable,
 } from "./resource-availability.js";
 
+// The first-sign-in flow: resolve the caller's identity account, provisioning
+// it on a first sign-in. One home for every surface (console gate, CLI,
+// platform builders' own gates).
+export {
+  ensureMyIdentityAccount,
+  type EnsuredIdentityAccount,
+  type EnsureMyIdentityAccountOptions,
+  type IdentityAccountLane,
+} from "./ensure-identity-account.js";
+
 // Authorization config and IAM role utilities
 export {
   getGrantableRoles,
@@ -126,10 +137,7 @@ export {
 } from "./github.js";
 
 // Platform client (server info / edition detection)
-export {
-  PlatformClient,
-  type ServerInfo,
-} from "./platform.js";
+export { PlatformClient, type ServerInfo } from "./platform.js";
 
 // Manifest engine (kind-agnostic YAML ⇄ proto ⇄ apply)
 export {
@@ -200,7 +208,11 @@ export {
   type AgentShareInput,
   type AgentShareMessagesInput,
 } from "./gen/agentshare.js";
-export { ApiKeyClient, toApiKeyUpdateInput, type ApiKeyInput } from "./gen/apikey.js";
+export {
+  ApiKeyClient,
+  toApiKeyUpdateInput,
+  type ApiKeyInput,
+} from "./gen/apikey.js";
 export {
   ChannelAppClient,
   toChannelAppUpdateInput,
@@ -226,10 +238,7 @@ export {
   toIdentityAccountUpdateInput,
   type IdentityAccountInput,
 } from "./gen/identityaccount.js";
-export {
-  InvitationClient,
-  type InvitationInput,
-} from "./gen/invitation.js";
+export { InvitationClient, type InvitationInput } from "./gen/invitation.js";
 export {
   IdentityProviderClient,
   toIdentityProviderUpdateInput,
@@ -274,7 +283,11 @@ export {
   toPlatformClientUpdateInput,
   type PlatformClientInput,
 } from "./gen/platformclient.js";
-export { ProjectClient, toProjectUpdateInput, type ProjectInput } from "./gen/project.js";
+export {
+  ProjectClient,
+  toProjectUpdateInput,
+  type ProjectInput,
+} from "./gen/project.js";
 export {
   ScheduleClient,
   buildScheduleProto,

package/src/platform.ts

@@ -3,11 +3,16 @@ import { create } from "@bufbuild/protobuf";
 import {
   GetServerInfoInputSchema,
   PlatformQueryController,
+} from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import type {
+  GetServerInfoOutput,
   ServerEdition,
 } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
-import type { GetServerInfoOutput } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 import { wrapError } from "./gen/errors.js";
-import type { DeploymentMode } from "./resource-availability.js";
+import {
+  deploymentModeOf,
+  type DeploymentMode,
+} from "./resource-availability.js";
 
 /** Server identity information returned by {@link PlatformClient.getServerInfo}. */
 export interface ServerInfo {
@@ -36,8 +41,10 @@ export class PlatformClient {
   /**
    * Retrieve the connected server's edition and version.
    *
-   * Maps the proto {@link ServerEdition} to a {@link DeploymentMode}:
+   * Maps the proto {@link ServerEdition} to a {@link DeploymentMode}
+   * through {@link deploymentModeOf}:
    * - `oss` -> `"local"`
+   * - `enterprise` -> `"enterprise"`
    * - `cloud` -> `"cloud"`
    * - unspecified/unknown -> `"cloud"` (safe default)
    */
@@ -47,7 +54,7 @@ export class PlatformClient {
         create(GetServerInfoInputSchema, {}),
       );
       return {
-        deploymentMode: resp.edition === ServerEdition.oss ? "local" : "cloud",
+        deploymentMode: deploymentModeOf(resp.edition),
         edition: resp.edition,
         version: resp.version,
       };

package/src/resource-availability.ts

@@ -1,27 +1,130 @@
-import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
-import { CLOUD_ONLY_KINDS } from "./gen/resource-availability.js";
+/**
+ * The edition vocabulary of the SDK: which edition a server is, in the
+ * SDK's own words, and whether a resource kind is served there.
+ *
+ * Four facts this module is built on (editions program, DD-001):
+ *
+ * - A kind's `ResourceTier` names the MINIMUM edition that serves it. The
+ *   editions are ordered oss < enterprise < cloud because each composes the
+ *   previous one's extension units, so a tier admits its own edition and
+ *   every edition above it.
+ * - The proto enums' numbers are wire identifiers, not ranks: `enterprise`
+ *   was added after `cloud` / `cloud_only` and sits at 3 in both. The two
+ *   rank functions below are the ONLY place a tier meets an edition; nothing
+ *   compares enum numbers.
+ * - `DeploymentMode` is `ServerEdition` in string-literal form, the shape
+ *   React consumers expect (`colorMode: "light" | "dark"` is the sibling),
+ *   with `oss` spelled `"local"` for history's sake. `deploymentModeOf` is
+ *   the ONE converter; it must never grow a second implementation.
+ * - An older client must not break against a newer server: an edition value
+ *   this SDK does not know maps to `"cloud"` (nothing hidden) instead of
+ *   throwing. The switch is exhaustive at compile time so a new edition is
+ *   still a compile error here; the runtime fallback is for the wire.
+ *
+ * `DeploymentMode` answers a TIER question ("is this kind served here?").
+ * Sites that use it to ask a FACILITY question ("does this server have a
+ * wallet?") compare `=== "cloud"` deliberately and say which facility they
+ * mean; see the React SDK's deployment-mode consumers.
+ */
+import {
+  ResourceTier,
+  type ApiResourceKind,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ServerEdition } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import { KIND_TIERS } from "./gen/resource-availability.js";
+
+/**
+ * Edition of the Stigmer backend the client is connected to, as reported
+ * by {@link PlatformClient.getServerInfo}.
+ *
+ * - `"local"` — Stigmer, the open-source edition. `open_source`-tier
+ *   resources are served.
+ * - `"enterprise"` — Stigmer Enterprise, self-hosted. `open_source`- and
+ *   `enterprise`-tier resources are served.
+ * - `"cloud"` — Stigmer Cloud. Every resource is served.
+ */
+export type DeploymentMode = "local" | "enterprise" | "cloud";
 
 /**
- * Deployment mode of the Stigmer backend the client is connected to.
+ * The one edition-to-mode converter.
  *
- * - `"local"` — Running against the local Go CLI server (OSS).
- *   Only `open_source`-tier resources are available.
- * - `"cloud"` — Running against Stigmer Cloud.
- *   All resources (including `cloud_only`) are available.
+ * `server_edition_unspecified` and any value this SDK does not know map to
+ * `"cloud"`: a broken or newer server hides nothing, which is the failure a
+ * client can live with. The `never` default keeps the switch exhaustive for
+ * the editions this SDK knows.
  */
-export type DeploymentMode = "local" | "cloud";
+export function deploymentModeOf(edition: ServerEdition): DeploymentMode {
+  switch (edition) {
+    case ServerEdition.oss:
+      return "local";
+    case ServerEdition.enterprise:
+      return "enterprise";
+    case ServerEdition.cloud:
+    case ServerEdition.server_edition_unspecified:
+      return "cloud";
+    default: {
+      const _exhaustive: never = edition;
+      void _exhaustive;
+      return "cloud";
+    }
+  }
+}
 
 /**
- * Check whether a resource kind is available in the given deployment mode.
+ * Check whether a resource kind is served in the given deployment mode.
  *
- * In cloud mode every resource is available. In local mode only
- * `open_source`-tier resources (those NOT in {@link CLOUD_ONLY_KINDS})
- * are available.
+ * A kind is served when the mode's edition ranks at or above the kind's
+ * minimum edition. Throws for a kind with no tier (only
+ * `api_resource_kind_unknown`): that is a programming error, and answering
+ * "available" for it would hide the bug.
  */
 export function isResourceAvailable(
   kind: ApiResourceKind,
   mode: DeploymentMode,
 ): boolean {
-  if (mode === "cloud") return true;
-  return !CLOUD_ONLY_KINDS.has(kind);
+  const tier = KIND_TIERS.get(kind);
+  if (tier === undefined) {
+    throw new Error(
+      `isResourceAvailable: kind ${kind} has no tier — only kinds with kind_meta can be asked about`,
+    );
+  }
+  return editionRank(mode) >= tierRank(tier);
+}
+
+/** Position of an edition in the oss < enterprise < cloud order. */
+function editionRank(mode: DeploymentMode): number {
+  switch (mode) {
+    case "local":
+      return 1;
+    case "enterprise":
+      return 2;
+    case "cloud":
+      return 3;
+    default: {
+      const _exhaustive: never = mode;
+      throw new Error(`unknown deployment mode: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+/** Position of a tier's minimum edition in the same order. */
+function tierRank(tier: ResourceTier): number {
+  switch (tier) {
+    case ResourceTier.open_source:
+      return 1;
+    case ResourceTier.enterprise:
+      return 2;
+    case ResourceTier.cloud_only:
+      return 3;
+    case ResourceTier.resource_tier_unspecified:
+      // A kind without a declared tier is treated as core: the generator
+      // emits every kind_meta tier verbatim, so this arm is reachable only
+      // by a proto that forgot the field, and hiding a kind is the worse
+      // failure for a client.
+      return 1;
+    default: {
+      const _exhaustive: never = tier;
+      throw new Error(`unknown resource tier: ${String(_exhaustive)}`);
+    }
+  }
 }