@volter/sdk 0.0.0-stage → 0.5.204

package/src/account.ts

@@ -0,0 +1,210 @@
+import { z } from 'zod';
+
+// Account identity and billing preference are host configuration, never generation-call inputs.
+export const AccountBackendSchema = z.enum(['mock', 'live']);
+export const AccountPlanSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  status: z.enum(['free', 'trialing', 'active', 'past_due', 'cancelling']),
+  interval: z.enum(['month', 'year']).optional(),
+  renewsAt: z.string().datetime().optional(),
+  endsAt: z.string().datetime().optional(),
+});
+export const AccountCreditsSchema = z.object({
+  included: z.number().nonnegative(),
+  purchased: z.number().nonnegative(),
+  used: z.number().nonnegative(),
+  reserved: z.number().nonnegative(),
+  remaining: z.number().nonnegative(),
+  resetsAt: z.string().datetime().optional(),
+  purchasedExpiresAt: z.string().datetime().optional(),
+});
+export const AccountSpendPolicySchema = z.object({
+  overageEnabled: z.boolean(),
+  monthlyLimitCredits: z.number().nonnegative(),
+  alertThresholds: z.array(z.number().min(1).max(100)).max(8),
+  autoReload: z
+    .object({
+      enabled: z.boolean(),
+      whenRemainingBelow: z.number().nonnegative(),
+      reloadTo: z.number().positive(),
+      monthlyLimitCredits: z.number().nonnegative(),
+    })
+    .optional(),
+});
+export const AccountAlertSchema = z.object({
+  id: z.string().min(1),
+  kind: z.enum(['threshold', 'auto_reload_succeeded', 'auto_reload_failed']),
+  message: z.string().min(1),
+  createdAt: z.string().datetime(),
+  readAt: z.string().datetime().optional(),
+});
+export const AccountUserSchema = z.object({
+  id: z.string().min(1),
+  email: z.string().email(),
+  name: z.string().min(1).optional(),
+});
+export const AccountOrganizationDomainSchema = z.object({
+  name: z.string().min(1),
+  verified: z.boolean(),
+  enrollmentMode: z.enum([
+    'manual_invitation',
+    'automatic_invitation',
+    'automatic_suggestion',
+    'enterprise_sso',
+  ]),
+});
+export const AccountOrganizationSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  slug: z.string().min(1).optional(),
+  role: z.string().min(1),
+  domains: z.array(AccountOrganizationDomainSchema).max(50),
+});
+export const AccountUsageEntrySchema = z.object({
+  id: z.string().min(1),
+  occurredAt: z.string().datetime(),
+  kind: z.enum(['inference', 'generation', 'workspace', 'storage', 'relay', 'deployment']),
+  provider: z.string().min(1),
+  operation: z.string().optional(),
+  credits: z.number().nonnegative(),
+  state: z.enum(['reserved', 'settled', 'released']),
+  externalId: z.string().optional(),
+});
+export const AccountPlanIdSchema = z.enum(['free', 'creator', 'max', 'ultra']);
+export const AccountCatalogSchema = z.object({
+  plans: z.object({
+    free: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+    creator: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+    max: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+    ultra: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+  }),
+  creditPacks: z.record(
+    z.string().min(1),
+    z.object({
+      name: z.string().min(1),
+      credits: z.number().int().positive(),
+      expiresInDays: z.number().int().positive().optional(),
+    }),
+  ),
+});
+export const AccountSnapshotSchema = z.discriminatedUnion('authenticated', [
+  z.object({ authenticated: z.literal(false), backend: AccountBackendSchema }),
+  z.object({
+    authenticated: z.literal(true),
+    backend: AccountBackendSchema,
+    user: AccountUserSchema,
+    organizations: z.array(AccountOrganizationSchema).max(100).optional(),
+    plan: AccountPlanSchema,
+    credits: AccountCreditsSchema,
+    spendPolicy: AccountSpendPolicySchema,
+    alerts: z.array(AccountAlertSchema).max(100).optional(),
+    entitlements: z.object({
+      generation: z.boolean(),
+      dailyJobs: z.number().int().positive().optional(),
+    }),
+  }),
+]);
+/** Product-facing routes. Provider tools may translate BYOK to their native
+ * transport name (`direct`) internally. */
+export const GenerationExecutionRouteSchema = z.enum(['auto', 'mock', 'managed', 'byok']);
+export const ProviderCredentialIdSchema = z.enum(['fal', 'tripo', 'worldlabs', 'openrouter']);
+export const CodingInferenceSettingsSchema = z.object({
+  enabled: z.boolean(),
+  provider: z.literal('openrouter'),
+  model: z.string().trim().min(1).max(256),
+});
+export const ProviderCredentialSourceSchema = z.enum(['environment', 'system', 'session', 'none']);
+export const ProviderCredentialStatusSchema = z.object({
+  provider: ProviderCredentialIdSchema,
+  label: z.string().min(1),
+  environmentVariable: z.string().min(1),
+  configured: z.boolean(),
+  source: ProviderCredentialSourceSchema,
+  editable: z.boolean(),
+  persistence: z.enum(['system', 'session']),
+  maskedKey: z.string().min(1).optional(),
+  problem: z.string().min(1).optional(),
+});
+export const ProviderCredentialTestResultSchema = z.object({
+  provider: ProviderCredentialIdSchema,
+  ok: z.literal(true),
+  testedAt: z.string().datetime(),
+});
+
+export type AccountBackend = z.infer<typeof AccountBackendSchema>;
+export type AccountPlan = z.infer<typeof AccountPlanSchema>;
+export type AccountCredits = z.infer<typeof AccountCreditsSchema>;
+export type AccountSpendPolicy = z.infer<typeof AccountSpendPolicySchema>;
+export type AccountAlert = z.infer<typeof AccountAlertSchema>;
+export type AccountUser = z.infer<typeof AccountUserSchema>;
+export type AccountOrganization = z.infer<typeof AccountOrganizationSchema>;
+export type AccountOrganizationDomain = z.infer<typeof AccountOrganizationDomainSchema>;
+export type AccountUsageEntry = z.infer<typeof AccountUsageEntrySchema>;
+export type AccountPlanId = z.infer<typeof AccountPlanIdSchema>;
+export type AccountCatalog = z.infer<typeof AccountCatalogSchema>;
+export type AccountSnapshot = z.infer<typeof AccountSnapshotSchema>;
+export type GenerationExecutionRoute = z.infer<typeof GenerationExecutionRouteSchema>;
+export type CodingInferenceSettings = z.infer<typeof CodingInferenceSettingsSchema>;
+export type ProviderCredentialId = z.infer<typeof ProviderCredentialIdSchema>;
+export type ProviderCredentialSource = z.infer<typeof ProviderCredentialSourceSchema>;
+export type ProviderCredentialStatus = z.infer<typeof ProviderCredentialStatusSchema>;
+export type ProviderCredentialTestResult = z.infer<typeof ProviderCredentialTestResultSchema>;
+export type EditorAccountSnapshot = AccountSnapshot & {
+  /** Which identity/payment surface backs this editor session. The in-process
+   * mock value exists only for isolated unit tests. */
+  accountEnvironment: 'test-mock' | 'development-twin' | 'production';
+  routes: { mock: true; managed: boolean; byok: boolean; byokProviders: string[] };
+  preferredRoute: GenerationExecutionRoute;
+  /** Editor-only metadata. Credential values never cross the server boundary. */
+  providerCredentials: ProviderCredentialStatus[];
+  codingInference: CodingInferenceSettings;
+};
+export interface GenerationAccountProjection {
+  routes: EditorAccountSnapshot['routes'];
+  preferredRoute: GenerationExecutionRoute;
+}
+export function generationAccountProjection(
+  account: EditorAccountSnapshot,
+): GenerationAccountProjection {
+  return {
+    routes: {
+      mock: true,
+      managed: account.routes.managed,
+      byok: account.routes.byok,
+      byokProviders: [...account.routes.byokProviders],
+    },
+    preferredRoute: account.preferredRoute,
+  };
+}
+export const EditorAccountSnapshotSchema: z.ZodType<EditorAccountSnapshot> = z.intersection(
+  AccountSnapshotSchema,
+  z.object({
+    accountEnvironment: z.enum(['test-mock', 'development-twin', 'production']),
+    routes: z.object({
+      mock: z.literal(true),
+      managed: z.boolean(),
+      byok: z.boolean(),
+      byokProviders: z.array(z.string().min(1)),
+    }),
+    preferredRoute: GenerationExecutionRouteSchema,
+    providerCredentials: z.array(ProviderCredentialStatusSchema),
+    codingInference: CodingInferenceSettingsSchema,
+  }),
+);

package/src/chrome.ts

@@ -0,0 +1,88 @@
+/**
+ * THE CHROME POINTS — palette actions and menu items a package contributes
+ * (WORKBENCH.md §Contribution points). Both are data: an id, a label and what
+ * happens on choose. The host renders them where its own live: a contributed
+ * action in the command palette beside the editor's, a contributed item at the
+ * end of the named application menu.
+ *
+ *   `profiler.action.ts`   export const point = 'workspace.action';  export const actions: ActionContribution['actions']
+ *   `navmesh.menu.ts`      export const point = 'workspace.menu';    export const menu: MenuContribution
+ *
+ * A contribution's id is namespaced by the host under `tool:` like a
+ * utility's, so it can never collide with an editor action. `disabled` is
+ * asked at render, so an item may follow session state (a bake that has no
+ * navigation adapter to run on).
+ */
+
+import type { EditorKeyActionId } from '@volter/project/adapter/editor-looks';
+
+export interface ContributedAction {
+  readonly id: string;
+  readonly label: string;
+  readonly execute: () => void | Promise<void>;
+  /** The key action this entry also is: the palette prints that action's chord
+   *  in the ACTIVE keymap beside it. */
+  readonly shortcut?: EditorKeyActionId;
+}
+
+export interface ActionContribution {
+  /**
+   * The palette actions — a fixed list, or a function for a LIVE set (one
+   * action per running XState actor): the host asks it when the palette
+   * opens and again whenever `subscribe` fires, the way a menu item's
+   * `disabled` is asked at render.
+   */
+  readonly actions: readonly ContributedAction[] | (() => readonly ContributedAction[]);
+  /** Fires when a live `actions` set moved. Returns the unsubscribe. */
+  readonly subscribe?: (listener: () => void) => () => void;
+}
+
+/** The application menus a package may append to (`edit` is the host's
+ *  own — its verbs are the history's and the selection's), and `asset`: the
+ *  Asset Browser's context menu on one asset, whose items receive the asset. */
+export type ContributableMenu = 'view' | 'window' | 'debug' | 'tools' | 'help' | 'asset';
+
+/** What a context menu's item is invoked ON. Empty for the application menus. */
+export interface MenuSubject {
+  /** The project-relative path of the asset the `asset` menu opened on. */
+  readonly assetPath?: string;
+}
+
+export interface ContributedMenuItem {
+  readonly id: string;
+  readonly label: string | (() => string);
+  readonly execute: (subject: MenuSubject) => void | Promise<void>;
+  readonly disabled?: (subject: MenuSubject) => boolean;
+  /** A `data-testid` for the item, when a driver needs to find it. */
+  readonly testId?: string;
+}
+
+export interface MenuContribution {
+  readonly menu: ContributableMenu;
+  readonly items: readonly ContributedMenuItem[];
+}
+
+/**
+ * A HEADER item (`.header.tsx`, `point = 'workspace.header'`): a component
+ * the host renders in the project header's transport cluster, in `order`.
+ * The Play transport is the worked case — a package that plays a game puts
+ * its play/pause/stop there; a project that declares nothing to run has an
+ * empty cluster.
+ */
+export interface HeaderContribution {
+  readonly order?: number;
+  /**
+   * Where the item renders: the project header's transport cluster (the
+   * default), or the 3D document's toolbar (`object3d-document`), where the
+   * component receives the open document's id and resolves its subject through
+   * its own integration. A runtime debug toggle on a mounted model lives there.
+   */
+  readonly placement?: HeaderPlacement;
+}
+
+export type HeaderPlacement = 'transport' | 'object3d-document';
+
+/** What a `object3d-document` header item is rendered with. */
+export interface DocumentHeaderItemProps {
+  readonly documentId: string;
+}