@maravilla-labs/types 0.2.4 → 0.3.0

package/index.d.ts

@@ -69,6 +69,75 @@ export interface KvStore {
      */
     list(namespace: string, options?: KvListRequest): Promise<KvListResponse>;
 }
+/** MongoDB-style key direction: `1` ascending, `-1` descending. */
+export type IndexDirection = 1 | -1;
+/** Whether an index is a regular document index or a vector index. */
+export type IndexKind = 'document' | 'vector';
+export interface IndexSpec {
+    name?: string;
+    keys: Array<[string, IndexDirection]> | Record<string, IndexDirection>;
+    unique?: boolean;
+    sparse?: boolean;
+    partial?: Record<string, unknown>;
+    expireAfterSeconds?: number;
+}
+export interface IndexDescriptor {
+    collection: string;
+    name: string;
+    keys: Array<[string, IndexDirection]>;
+    unique: boolean;
+    sparse: boolean;
+    partial?: Record<string, unknown>;
+    expireAfterSeconds?: number;
+    kind: IndexKind;
+}
+/** Distance metric used to compare vectors. */
+export type VectorMetric = 'cosine' | 'l2' | 'hamming';
+/**
+ * On-disk storage precision for vectors.
+ * - `float32` (default): 4 bytes per dim
+ * - `int8`: 1 byte per dim, 4× smaller, typically <2% accuracy loss
+ * - `bit`: 1 bit per dim, 32× smaller; requires metric='hamming'
+ */
+export type VectorStorage = 'float32' | 'int8' | 'bit';
+/** Query shape: single vector or an array of vectors (ColBERT-style). */
+export type VectorQueryMode = 'single' | 'late-interaction';
+/** How multi-vector distances are aggregated per document. */
+export type VectorAggregation = 'max-sim' | 'sum';
+/** Spec used to declare a vector index on a collection field. */
+export interface VectorIndexSpec {
+    field: string;
+    dimensions: number;
+    metric?: VectorMetric;
+    storage?: VectorStorage;
+    matryoshka?: boolean;
+    multiVector?: boolean;
+}
+/** Metadata for a registered vector index. */
+export interface VectorIndexDescriptor {
+    collection: string;
+    field: string;
+    dimensions: number;
+    metric: VectorMetric;
+    storage: VectorStorage;
+    matryoshka: boolean;
+    multiVector: boolean;
+}
+/** Vector search clause riding inside DbFindOptions. */
+export interface VectorQuery {
+    field: string;
+    value: number[] | number[][];
+    k: number;
+    metric?: VectorMetric;
+    minScore?: number;
+    queryMode?: VectorQueryMode;
+    aggregation?: VectorAggregation;
+}
+/** Document returned by a vector search with similarity metadata attached. */
+export type VectorSearchHit = Record<string, any> & {
+    _score: number;
+    _distance: number;
+};
 /**
  * Database find options
  */
@@ -77,6 +146,8 @@ export interface DbFindOptions {
     skip?: number;
     sort?: Record<string, 1 | -1>;
     projection?: Record<string, 1 | 0>;
+    /** Hybrid metadata + vector search clause. */
+    vector?: VectorQuery;
 }
 /**
  * Database collection interface
@@ -203,64 +274,180 @@ export interface Storage {
      */
     getMetadata(key: string): Promise<StorageMetadata>;
 }
-/**
- * Authenticated user record
- */
-export interface AuthUser {
+/** Delegation mode for stewardship overrides */
+export type DelegationMode = 'full' | 'scoped';
+/** Status of a stewardship override */
+export type StewardshipStatus = 'active' | 'suspended' | 'revoked' | 'expired';
+/** A scoped permission entry */
+export interface ScopedPermission {
+    /** Resource name */
+    resource: string;
+    /** Allowed actions on the resource */
+    actions: string[];
+}
+/** A stewardship override record */
+export interface StewardshipOverride {
+    id: string;
+    steward_id: string;
+    ward_id: string;
+    delegation_mode: DelegationMode;
+    scoped_permissions: ScopedPermission[];
+    valid_from?: number;
+    valid_until?: number;
+    status: StewardshipStatus;
+    reason?: string;
+    source: string;
+    source_circle_id?: string;
+    source_relation_type_id?: string;
+    created_at: number;
+    updated_at: number;
+}
+/** Options for creating a stewardship override */
+export interface CreateStewardshipOverrideRequest {
+    steward_id: string;
+    ward_id: string;
+    delegation_mode?: DelegationMode;
+    scoped_permissions?: ScopedPermission[];
+    valid_from?: number;
+    valid_until?: number;
+    reason?: string;
+}
+/** Result of resolving stewardship for a user */
+export interface StewardshipResolution {
+    /** Users who are stewards of this user */
+    stewards: StewardshipOverride[];
+    /** Users this user is a steward of */
+    wards: StewardshipOverride[];
+}
+/** Context for acting as another user */
+export interface ActAsContext {
+    steward_id: string;
+    ward_id: string;
+    delegation_mode: DelegationMode;
+    scoped_permissions: ScopedPermission[];
+    session_token: string;
+    expires_at: number;
+}
+/** An entry in the stewardship audit log */
+export interface StewardshipAuditEntry {
+    id: string;
+    performed_by: string;
+    on_behalf_of: string;
+    action: string;
+    resource?: string;
+    details?: Record<string, any>;
+    created_at: number;
+}
+/** Options for listing audit log entries */
+export interface AuditListOptions {
+    limit?: number;
+    offset?: number;
+}
+/** Stewardship service interface */
+export interface Stewardship {
+    resolve(userId: string): Promise<StewardshipResolution>;
+    createOverride(options: CreateStewardshipOverrideRequest): Promise<StewardshipOverride>;
+    revoke(id: string): Promise<void>;
+    checkPermission(stewardId: string, wardId: string, resource: string, action: string): Promise<boolean>;
+    createActAs(stewardId: string, wardId: string): Promise<ActAsContext>;
+    listAudit(userId: string, options?: AuditListOptions): Promise<StewardshipAuditEntry[]>;
+}
+/** A platform resource definition */
+export interface Resource {
     id: string;
+    resource_name: string;
+    title: string;
+    description?: string;
+    actions: string[];
+    created_at: number;
+    updated_at: number;
+}
+/** Options for creating a resource */
+export interface CreateResourceRequest {
+    resource_name: string;
+    title: string;
+    description?: string;
+    actions?: string[];
+}
+/** Circle membership entry */
+export interface CircleMembership {
+    user_id: string;
     email: string;
-    email_verified: boolean;
-    status: 'active' | 'suspended' | 'deactivated';
-    provider: string;
-    groups: string[];
+    relationship: string;
+    is_primary_contact: boolean;
+    joined_at: number;
+}
+/** A circle */
+export interface Circle {
+    id: string;
+    name: string;
+    metadata?: Record<string, any>;
+    member_count: number;
     created_at: number;
     updated_at: number;
-    last_login_at?: number;
 }
-
-/**
- * Session returned after login or refresh
- */
-export interface AuthSession {
-    access_token: string;
-    refresh_token: string;
-    expires_in: number;
-    user: AuthUser;
+/** State of a workflow run. */
+export type WorkflowRunStatus = 'queued' | 'running' | 'sleeping' | 'waiting_event' | 'completed' | 'failed' | 'cancelled';
+/** Kind of a recorded step. */
+export type WorkflowStepKind = 'run' | 'sleep' | 'wait_event' | 'ai' | 'mcp' | 'invoke';
+export interface WorkflowRun {
+    runId: string;
+    workflowId: string;
+    projectId?: string;
+    deploymentId: string;
+    input: unknown;
+    status: WorkflowRunStatus;
+    attempt: number;
+    createdAt: number;
+    updatedAt: number;
+    completedAt?: number;
+    output?: unknown;
+    error?: unknown;
 }
-
-/**
- * Custom registration field
- */
-export interface AuthField {
-    key: string;
-    label: string;
-    field_type: string;
-    required: boolean;
-    show_on_register: boolean;
+export interface WorkflowStepRecord {
+    name: string;
+    kind: WorkflowStepKind;
+    status: 'pending' | 'completed' | 'failed';
+    output?: unknown;
+    error?: unknown;
+    startedAt: number;
+    completedAt?: number;
+    wakeAt?: number;
 }
-
 /**
- * Auth service for end-user authentication
+ * Handle returned by `platform.workflows.start()` — lets callers poll
+ * status, await the final result, cancel, or signal an event.
  */
-export interface AuthService {
-    register(options: { email: string; password: string; profile?: Record<string, any> }): Promise<AuthUser>;
-    login(options: { email: string; password: string }): Promise<AuthSession>;
-    validate(accessToken: string): Promise<AuthUser>;
-    refresh(refreshToken: string): Promise<AuthSession>;
-    logout(sessionId: string): Promise<void>;
-    getUser(userId: string): Promise<AuthUser | null>;
-    listUsers(filter?: { limit?: number; offset?: number; status?: string; email_contains?: string }): Promise<{ users: AuthUser[]; total: number; limit: number; offset: number }>;
-    updateUser(userId: string, update: { email?: string; status?: string; profile?: Record<string, any> }): Promise<AuthUser>;
-    deleteUser(userId: string): Promise<void>;
-    sendVerification(userId: string): Promise<{ token: string }>;
-    verifyEmail(token: string): Promise<void>;
-    sendPasswordReset(email: string): Promise<{ token: string }>;
-    resetPassword(token: string, newPassword: string): Promise<void>;
-    changePassword(userId: string, oldPassword: string, newPassword: string): Promise<void>;
-    getFieldConfig(): Promise<{ fields: AuthField[] }>;
-    withAuth<T extends (request: Request & { user: AuthUser }) => Promise<Response>>(handler: T): (request: Request) => Promise<Response>;
-}
-
+export interface WorkflowHandle {
+    /** The run's unique id. */
+    readonly runId: string;
+    /** Current run record, or null if the run doesn't exist. */
+    status(): Promise<WorkflowRun | null>;
+    /** Full step history — useful for debugging. */
+    history(): Promise<WorkflowStepRecord[]>;
+    /**
+     * Wait for the run to reach a terminal state and return its output.
+     * Throws if the run ended in `failed` or `cancelled`.
+     */
+    result(options?: {
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    /** Best-effort cancellation. Returns `true` if it transitioned. */
+    cancel(): Promise<boolean>;
+}
+export interface Workflows {
+    /** Start a new run of the workflow with the given input. */
+    start(workflowId: string, input?: unknown): Promise<WorkflowHandle>;
+    /** Get a handle to an existing run without starting one. */
+    handle(runId: string): WorkflowHandle;
+    /**
+     * Signal an event to any runs paused on `step.waitForEvent`. Returns
+     * the number of runs resolved. Matching rules: `eventType` must equal
+     * the filter's `type` (if set); each key in the filter's `match`
+     * must be present in `payload` with an equal value.
+     */
+    sendEvent(eventType: string, payload?: unknown): Promise<number>;
+}
 /**
  * Main platform interface available in runtime
  */
@@ -271,8 +458,50 @@ export interface Platform {
     db: Database;
     /** Storage service instance */
     storage: Storage;
-    /** Auth service for end-user authentication */
-    auth: AuthService;
+    /** Durable multi-step workflows */
+    workflows: Workflows;
+    /** Auth service with stewardship, resources, and circle helpers */
+    auth: {
+        register(options: {
+            email: string;
+            password: string;
+            profile?: Record<string, any>;
+        }): Promise<any>;
+        login(options: {
+            email: string;
+            password: string;
+        }): Promise<any>;
+        validate(accessToken: string): Promise<any>;
+        refresh(refreshToken: string): Promise<any>;
+        logout(sessionId: string): Promise<void>;
+        getUser(userId: string): Promise<any>;
+        listUsers(filter?: Record<string, any>): Promise<any>;
+        updateUser(userId: string, update: Record<string, any>): Promise<any>;
+        deleteUser(userId: string): Promise<void>;
+        sendVerification(userId: string): Promise<any>;
+        verifyEmail(token: string): Promise<void>;
+        sendPasswordReset(email: string): Promise<any>;
+        resetPassword(token: string, newPassword: string): Promise<void>;
+        changePassword(userId: string, oldPassword: string, newPassword: string): Promise<void>;
+        getFieldConfig(): Promise<any>;
+        getOAuthUrl(provider: string, options?: {
+            redirectUri?: string;
+        }): Promise<any>;
+        handleOAuthCallback(provider: string, params: {
+            code: string;
+            state: string;
+        }): Promise<any>;
+        /** Stewardship (guardian/ward delegation) */
+        stewardship: Stewardship;
+        /** List available resources */
+        listResources(): Promise<Resource[]>;
+        /** Create a resource definition */
+        createResource(options: CreateResourceRequest): Promise<Resource>;
+        /** Get circle members */
+        getCircleMembers(circleId: string): Promise<CircleMembership[]>;
+        /** Get circles a user belongs to */
+        getUserCircles(userId: string): Promise<Circle[]>;
+    };
     /** Legacy aliases for compatibility */
     env: {
         KV: KvStore;

package/index.ts

@@ -451,6 +451,81 @@ export interface Circle {
 
 // Platform Types
 
+// --- Workflows ---
+
+/** State of a workflow run. */
+export type WorkflowRunStatus =
+  | 'queued'
+  | 'running'
+  | 'sleeping'
+  | 'waiting_event'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+/** Kind of a recorded step. */
+export type WorkflowStepKind = 'run' | 'sleep' | 'wait_event' | 'ai' | 'mcp' | 'invoke';
+
+export interface WorkflowRun {
+  runId: string;
+  workflowId: string;
+  projectId?: string;
+  deploymentId: string;
+  input: unknown;
+  status: WorkflowRunStatus;
+  attempt: number;
+  createdAt: number;
+  updatedAt: number;
+  completedAt?: number;
+  output?: unknown;
+  error?: unknown;
+}
+
+export interface WorkflowStepRecord {
+  name: string;
+  kind: WorkflowStepKind;
+  status: 'pending' | 'completed' | 'failed';
+  output?: unknown;
+  error?: unknown;
+  startedAt: number;
+  completedAt?: number;
+  wakeAt?: number;
+}
+
+/**
+ * Handle returned by `platform.workflows.start()` — lets callers poll
+ * status, await the final result, cancel, or signal an event.
+ */
+export interface WorkflowHandle {
+  /** The run's unique id. */
+  readonly runId: string;
+  /** Current run record, or null if the run doesn't exist. */
+  status(): Promise<WorkflowRun | null>;
+  /** Full step history — useful for debugging. */
+  history(): Promise<WorkflowStepRecord[]>;
+  /**
+   * Wait for the run to reach a terminal state and return its output.
+   * Throws if the run ended in `failed` or `cancelled`.
+   */
+  result(options?: { timeoutMs?: number }): Promise<unknown>;
+  /** Best-effort cancellation. Returns `true` if it transitioned. */
+  cancel(): Promise<boolean>;
+}
+
+export interface Workflows {
+  /** Start a new run of the workflow with the given input. */
+  start(workflowId: string, input?: unknown): Promise<WorkflowHandle>;
+  /** Get a handle to an existing run without starting one. */
+  handle(runId: string): WorkflowHandle;
+  /**
+   * Signal an event to any runs paused on `step.waitForEvent`. Returns
+   * the number of runs resolved. Matching rules: `eventType` must equal
+   * the filter's `type` (if set); each key in the filter's `match`
+   * must be present in `payload` with an equal value.
+   */
+  sendEvent(eventType: string, payload?: unknown): Promise<number>;
+}
+
 /**
  * Main platform interface available in runtime
  */
@@ -461,6 +536,8 @@ export interface Platform {
   db: Database;
   /** Storage service instance */
   storage: Storage;
+  /** Durable multi-step workflows */
+  workflows: Workflows;
   /** Auth service with stewardship, resources, and circle helpers */
   auth: {
     register(options: { email: string; password: string; profile?: Record<string, any> }): Promise<any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/types",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "TypeScript definitions for Maravilla Runtime platform APIs",
   "main": "index.ts",
   "types": "index.ts",