@sylphx/sdk 0.3.7 → 0.5.0

package/dist/index.d.ts

@@ -1,140 +1,170 @@
 import * as openapi_fetch from 'openapi-fetch';
 
 /**
- * SDK Configuration
- *
- * Create a config object that can be passed to SDK functions.
- * This is the foundation for the function-based API.
- *
- * Uses appId or secretKey for authentication via x-app-secret header.
- */
-/**
- * Parsed representation of a Sylphx API key (ADR-021 format).
- */
-interface ParsedKey {
-    /** Key type: 'pk' (publishable) or 'sk' (secret) */
-    type: 'pk' | 'sk';
-    /** Environment short code: 'prod', 'dev', 'stg', or 'prev' */
-    env: 'prod' | 'dev' | 'stg' | 'prev';
-    /** 12-char project ref (base36) */
-    ref: string;
-    /** Random secret portion of the key */
-    token: string;
-    /** Whether this is a client-safe publishable key */
-    isPublic: boolean;
-    /** Pre-computed base URL for this project */
-    baseUrl: string;
+ * Sylphx Connection URL Parser — SDK Self-Contained Copy
+ *
+ * Implements the canonical connection string format defined in ADR-055 §5.
+ * This is a self-contained copy for SDK package independence (no app imports).
+ *
+ * Format:
+ *   sylphx://{credential}@{slug}.{domain}[:port][/v{version}]
+ *
+ * Examples:
+ *   sylphx://pk_prod_f19e5cdc3cc54f7ff81bdc26ec5bfbad@bold-river-a1b2c3.sylphx.com
+ *   sylphx://sk_prod_5120bfeb5120bfeb5120bfeb5120bfeb@bold-river-a1b2c3.sylphx.com/v1
+ *   sylphx://pk_dev_abc12345abc12345abc12345abc12345@calm-peak-z9x4d5.sylphx.dev
+ *
+ * Invariants:
+ *   - Protocol is always `sylphx:` (no exceptions)
+ *   - Credential matches `(pk|sk)_(dev|stg|prod|prev)_[a-f0-9]{32,64}`
+ *   - Host's first DNS label is the resource slug (validated by slug regex)
+ *   - `apiBaseUrl` is always HTTPS, with `/v{version}` appended (default `v1`)
+ *
+ * Parsing uses the WHATWG `URL` constructor — custom regex parsing is banned
+ * because it is notoriously brittle (ADR-055 §5.3).
+ */
+type ConnectionCredentialType = 'pk' | 'sk';
+type ConnectionEnv = 'dev' | 'stg' | 'prod' | 'prev';
+interface ParsedConnectionUrl {
+    /** Full credential string, e.g. `pk_prod_f19e...` */
+    readonly credential: string;
+    /** Credential kind — `pk` (publishable) or `sk` (secret) */
+    readonly credentialType: ConnectionCredentialType;
+    /** Target environment encoded in the credential */
+    readonly env: ConnectionEnv;
+    /** First DNS label of the host — the resource slug (e.g. `bold-river-a1b2c3`) */
+    readonly slug: string;
+    /** Full host including port when present (e.g. `bold-river-a1b2c3.sylphx.com`) */
+    readonly host: string;
+    /** Ready-to-use SDK base URL, always HTTPS (e.g. `https://bold-river-a1b2c3.sylphx.com/v1`) */
+    readonly apiBaseUrl: string;
+}
+declare class InvalidConnectionUrlError extends Error {
+    readonly code: "INVALID_CONNECTION_URL";
+    constructor(message: string);
 }
+
 /**
- * Parse an ADR-021 API key into its component parts.
+ * SDK Configuration — ADR-055 Connection URL API
+ *
+ * v0.5.0: The primary entry point is `createClient(url)` which accepts
+ * a `sylphx://` connection URL. The old `createConfig({ ref, publicKey })`
+ * API is removed.
  *
- * Supports:
- *   pk_{env}_{ref}_{32hex}   — publishable key (ADR-021)
- *   sk_{env}_{ref}_{64hex}   — secret key (ADR-021)
+ * @example
+ * ```typescript
+ * import { createClient } from '@sylphx/sdk'
  *
- * @throws SylphxError if key format is invalid or uses old app_* format
+ * const sylphx = createClient(process.env.SYLPHX_URL!)
+ * // Parses: sylphx://pk_prod_{hex}@bold-river-a1b2c3.sylphx.com
+ * ```
  */
-declare function parseKey(key: string): ParsedKey;
+
 /**
- * SDK Configuration for Pure Functions
+ * SDK Configuration object — immutable, frozen.
  *
- * This is the configuration object passed to pure SDK functions like
- * `track()`, `signIn()`, `getPlans()`, etc.
- *
- * ## Config Type Hierarchy
- *
- * - `SylphxConfig` (this) — Pure functions, server or client
- * - `SylphxClientConfig` — React hooks return value (appId, platformUrl only)
- * - `SylphxProviderProps` — React provider component props
- * - `SylphxMiddlewareConfig` — Next.js middleware options
- *
- * @example Server-side usage
- * ```ts
- * import { createConfig, track } from '@sylphx/sdk'
- *
- * const config = createConfig({ secretKey: process.env.SYLPHX_SECRET_KEY! })
- * await track(config, { event: 'purchase', properties: { amount: 99 } })
- * ```
+ * Created by `createClient()` or `createServerClient()`.
+ * Passed to all pure SDK functions (`track()`, `signIn()`, etc.).
  */
 interface SylphxConfig {
+    /** The credential string (pk_* or sk_*) */
+    readonly credential: string;
+    /** Credential type: 'pk' (publishable) or 'sk' (secret) */
+    readonly credentialType: 'pk' | 'sk';
+    /** Target environment: dev, stg, prod, or prev */
+    readonly env: 'dev' | 'stg' | 'prod' | 'prev';
+    /** Resource slug (first DNS label), e.g. 'bold-river-a1b2c3' */
+    readonly slug: string;
+    /** Pre-computed API base URL, e.g. 'https://bold-river-a1b2c3.sylphx.com/v1' */
+    readonly baseUrl: string;
+    /** Optional access token for authenticated requests */
+    readonly accessToken?: string;
     /**
-     * Secret key (sk_*) — full access, server-side only.
-     * Embed project ref, env, and routing info (ADR-021).
-     * Get from Platform Console → Apps → Your App → Environments.
+     * Secret key — populated when credentialType is 'sk'.
+     * Backward-compatible alias for `credential` when credential is sk_*.
      */
     readonly secretKey?: string;
     /**
-     * Publishable key (pk_*) — client-safe, read-only access.
-     * Embeds project ref, env, and routing info (ADR-021).
-     * Get from Platform Console → Apps → Your App → Environments.
+     * Publishable key — populated when credentialType is 'pk'.
+     * Backward-compatible alias for `credential` when credential is pk_*.
      */
     readonly publicKey?: string;
     /**
-     * Project ref — 12-char lowercase alphanumeric string.
-     * Extracted from the key automatically (ADR-021).
-     * The SDK targets: https://{ref}.api.sylphx.com/v1
+     * @deprecated Use `slug`. Backward-compatible alias.
      */
     readonly ref: string;
-    /**
-     * Pre-computed base URL: https://{ref}.api.sylphx.com/v1
-     * Derived from the embedded ref in the key.
-     */
-    readonly baseUrl: string;
-    /** Optional: Current access token for authenticated requests */
-    readonly accessToken?: string;
 }
 /**
- * Configuration input — ADR-021 key-first API.
+ * Explicit components input — alternative to connection URL string.
  *
- * Provide either publicKey or secretKey (or both).
- * The project ref is extracted automatically from the key.
+ * For multi-tenant apps or cases where components are stored separately.
  */
-interface SylphxConfigInput {
-    /**
-     * Publishable key (pk_*) — client-safe.
-     * Format: pk_{env}_{ref}_{32hex}
-     * env var: NEXT_PUBLIC_SYLPHX_KEY
-     */
+interface SylphxClientInput {
+    /** Resource slug, e.g. 'bold-river-a1b2c3' */
+    slug?: string;
+    /** Publishable key (pk_*) — client-safe */
     publicKey?: string;
-    /**
-     * Secret key (sk_*) — server-side only.
-     * Format: sk_{env}_{ref}_{64hex}
-     * env var: SYLPHX_SECRET_KEY
-     */
+    /** Secret key (sk_*) — server-side only */
     secretKey?: string;
+    /** Optional access token */
+    accessToken?: string;
+    /** API domain override (default: sylphx.com) */
+    domain?: string;
     /**
-     * @deprecated Use publicKey or secretKey — ref is now embedded in keys (ADR-021).
-     * Still accepted for backward compatibility; overridden by key-embedded ref.
+     * @deprecated Use `slug`. Accepted for backward compatibility during migration.
      */
     ref?: string;
-    accessToken?: string;
+    /**
+     * @deprecated Use `domain`. Accepted for backward compatibility during migration.
+     */
+    platformUrl?: string;
 }
 /**
- * Create a Sylphx configuration object (ADR-021 key-first API).
+ * Create a Sylphx client from a connection URL or explicit components.
  *
- * The project ref is extracted from the key automatically — no need to configure
- * NEXT_PUBLIC_SYLPHX_APP_ID separately.
+ * This is the primary SDK entry point for client-side (browser) usage.
+ * Accepts a `sylphx://` connection URL or an explicit components object.
  *
- * Validates key format, extracts ref, builds base URL.
- * Throws if key format is invalid.
+ * @example Connection URL (recommended)
+ * ```typescript
+ * const sylphx = createClient(process.env.NEXT_PUBLIC_SYLPHX_URL!)
+ * // Parses: sylphx://pk_prod_{hex}@bold-river-a1b2c3.sylphx.com
+ * ```
  *
- * @example Server-side (secret key)
+ * @example Explicit components
  * ```typescript
- * const config = createConfig({
- *   secretKey: process.env.SYLPHX_SECRET_KEY!,
+ * const sylphx = createClient({
+ *   slug: 'bold-river-a1b2c3',
+ *   publicKey: 'pk_prod_f19e...',
  * })
  * ```
+ */
+declare function createClient(input: string | SylphxClientInput): SylphxConfig;
+/**
+ * Create a Sylphx server client from a connection URL or explicit components.
  *
- * @example Client-side (publishable key)
+ * Equivalent to `createClient()` but validates that a secret key (sk_*) is provided.
+ * Use this for server-side operations that require elevated permissions.
+ *
+ * @example Connection URL (recommended)
  * ```typescript
- * const config = createConfig({
- *   publicKey: process.env.NEXT_PUBLIC_SYLPHX_KEY!,
+ * const sylphx = createServerClient(process.env.SYLPHX_SECRET_URL!)
+ * // Parses: sylphx://sk_prod_{hex}@bold-river-a1b2c3.sylphx.com
+ * ```
+ *
+ * @example Explicit components
+ * ```typescript
+ * const sylphx = createServerClient({
+ *   slug: 'bold-river-a1b2c3',
+ *   secretKey: 'sk_prod_5120...',
  * })
  * ```
  */
-declare function createConfig(input: SylphxConfigInput): SylphxConfig;
+declare function createServerClient(input: string | SylphxClientInput): SylphxConfig;
 /**
- * Create a new config with an updated access token
+ * Create a new config with an updated access token.
+ *
+ * Returns a new frozen config — does not mutate the original.
  *
  * @example
  * ```typescript
@@ -142,6 +172,15 @@ declare function createConfig(input: SylphxConfigInput): SylphxConfig;
  * ```
  */
 declare function withToken(config: SylphxConfig, accessToken: string): SylphxConfig;
+/**
+ * @deprecated Use `createClient()` or `createServerClient()` instead.
+ * This function is kept temporarily for migration but will be removed.
+ */
+type SylphxConfigInput = string | SylphxClientInput;
+/**
+ * @deprecated Use `createClient()` instead. See ADR-055.
+ */
+declare const createConfig: typeof createClient;
 
 /**
  * SDK Debug Mode
@@ -19946,6 +19985,16 @@ declare class SylphxError extends Error {
     static isRateLimited(err: unknown): err is SylphxError & {
         code: 'TOO_MANY_REQUESTS';
     };
+    /**
+     * Check if error is an account lockout error (too many failed login attempts).
+     * When true, `error.data?.lockoutUntil` contains the ISO 8601 timestamp when the lockout expires.
+     */
+    static isAccountLocked(err: unknown): err is SylphxError & {
+        code: 'TOO_MANY_REQUESTS';
+        data: {
+            lockoutUntil: string | null;
+        };
+    };
     /**
      * Check if error is a quota exceeded error (plan limit reached)
      */
@@ -21352,11 +21401,16 @@ interface RegisterInput {
     invitationToken?: string;
 }
 /**
- * Org context claims present in org-scoped tokens.
+ * Org context claims present in org-scoped tokens (after switch-org).
+ *
+ * The JWT carries the role key only. Permissions are resolved server-side
+ * via Redis-cached role→permissions lookup (WorkOS pattern). This keeps
+ * tokens small and ensures permission changes take effect without token refresh.
  */
 interface OrgTokenPayload {
     org_id: string;
     org_slug: string;
+    /** RBAC role key (e.g. "hr_manager", "admin"). Permissions resolved server-side. */
     org_role: string;
 }
 /**
@@ -22309,6 +22363,32 @@ type NativeStepContext = {
      * @param duration  Human-readable duration: '5s', '30m', '2h', '1d'.
      */
     sleep(name: string, duration: string): Promise<void>;
+    /**
+     * Pause execution until a named event is published via TriggersClient.publishEvent().
+     *
+     * On first encounter: signals the platform to wait for the event; stops execution.
+     * After the event arrives: returns the event payload.
+     * If timeout expires before event arrives: returns null.
+     *
+     * @param name      Step identifier (must be unique within the handler).
+     * @param eventName The event name to listen for (e.g. 'user.approved').
+     * @param options   Optional timeout ('24h', '7d') and payload filter.
+     *
+     * @example Human-in-the-loop approval
+     * ```typescript
+     * const approval = await step.waitForEvent<{ approvedBy: string }>(
+     *   'wait-approval',
+     *   'order.approved',
+     *   { timeout: '48h', filter: { orderId: payload.orderId } },
+     * )
+     * if (!approval) throw new Error('Approval timed out')
+     * await notifyCustomer(approval.approvedBy)
+     * ```
+     */
+    waitForEvent<T = unknown>(name: string, eventName: string, options?: {
+        timeout?: string;
+        filter?: Record<string, unknown>;
+    }): Promise<T | null>;
 };
 /**
  * A named task definition registered with sylphx.tasks.define().
@@ -22401,9 +22481,9 @@ declare class StepSleepSignal {
  * Build the step proxy for a single handler invocation.
  *
  * @param completedSteps  Map of stepName → cached result
- * @param resolvedWaits   Set of stepNames whose sleeps have been satisfied
+ * @param resolvedWaits   Map of stepName → wait result (sleep = undefined, event = event payload)
  */
-declare function createStepContext(completedSteps: Map<string, unknown>, resolvedWaits: Set<string>): NativeStepContext;
+declare function createStepContext(completedSteps: Map<string, unknown>, resolvedWaits: Map<string, unknown>): NativeStepContext;
 /**
  * Constant-time HMAC-SHA256 signature verification.
  * Accepts both raw hex and 'sha256={hex}' formats.
@@ -23788,6 +23868,350 @@ declare function canManageSettings(membership: OrganizationMembership | null): b
  */
 declare function canDeleteOrganization(membership: OrganizationMembership | null): boolean;
 
+/**
+ * Permission Functions
+ *
+ * Pure functions for permission management — no hidden state.
+ * Each function takes config as the first parameter.
+ *
+ * Uses REST API at /permissions/* for project-scoped operations.
+ * Uses REST API at /orgs/{orgId}/members/{memberId}/permissions for member checks.
+ *
+ * Types are self-contained (not dependent on generated OpenAPI spec) because
+ * the RBAC routes were added after the last spec generation.
+ */
+
+/**
+ * A permission definition within a project.
+ *
+ * Permissions are the atomic building blocks of RBAC roles.
+ * They use colon-separated keys (e.g. "org:members:read", "payroll:approve").
+ */
+interface Permission {
+    /** Prefixed permission ID (e.g. "perm_xxx") */
+    id: string;
+    /** Unique key within the project (e.g. "org:members:read") */
+    key: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description: string | null;
+    /** Whether this is a system-defined permission (immutable) */
+    isSystem: boolean;
+    /** ISO 8601 creation timestamp */
+    createdAt: string;
+}
+/**
+ * Input for creating a custom permission.
+ */
+interface CreatePermissionInput {
+    /** Unique key — colon-separated lowercase segments (e.g. "org:leave:approve") */
+    key: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+}
+/**
+ * Resolved permissions for a member, including their assigned role.
+ */
+interface MemberPermissionsResult {
+    /** Prefixed user ID of the member */
+    memberId: string;
+    /** Assigned role (null if no role assigned) */
+    role: {
+        key: string;
+        name: string;
+    } | null;
+    /** Flattened, deduplicated permission keys from all assigned roles */
+    permissions: string[];
+}
+/**
+ * List all permissions for the current project.
+ *
+ * Returns both system-defined and custom permissions.
+ * Requires a secret key (server-side only).
+ *
+ * @example
+ * ```typescript
+ * const { permissions } = await listPermissions(config)
+ * console.log(permissions.map(p => p.key))
+ * // ['org:members:read', 'org:members:manage', 'payroll:view', ...]
+ * ```
+ */
+declare function listPermissions(config: SylphxConfig): Promise<{
+    permissions: Permission[];
+}>;
+/**
+ * Create a custom permission for the project.
+ *
+ * Permission keys must be colon-separated lowercase segments
+ * (e.g. "org:leave:approve", "payroll:run").
+ * Requires a secret key (server-side only).
+ *
+ * @example
+ * ```typescript
+ * const { permission } = await createPermission(config, {
+ *   key: 'payroll:approve',
+ *   name: 'Approve Payroll',
+ *   description: 'Can approve payroll runs for the organization',
+ * })
+ * ```
+ */
+declare function createPermission(config: SylphxConfig, input: CreatePermissionInput): Promise<{
+    permission: Permission;
+}>;
+/**
+ * Delete a custom permission by key.
+ *
+ * System permissions cannot be deleted.
+ * Role-permission assignments are removed automatically via cascading delete.
+ * Requires a secret key (server-side only).
+ *
+ * @example
+ * ```typescript
+ * const { success } = await deletePermission(config, 'payroll:approve')
+ * ```
+ */
+declare function deletePermission(config: SylphxConfig, permissionKey: string): Promise<{
+    success: boolean;
+}>;
+/**
+ * Get a member's resolved permissions within an organization.
+ *
+ * Returns the flattened, deduplicated set of permission keys from all
+ * roles assigned to the member. Also returns their current role info.
+ * Requires the caller to be a member of the same organization.
+ *
+ * @example
+ * ```typescript
+ * const result = await getMemberPermissions(config, 'my-org', 'usr_abc123')
+ * console.log(result.permissions)
+ * // ['org:members:read', 'payroll:view', 'payroll:approve']
+ * console.log(result.role)
+ * // { key: 'hr_manager', name: 'HR Manager' }
+ * ```
+ */
+declare function getMemberPermissions(config: SylphxConfig, orgIdOrSlug: string, memberId: string): Promise<MemberPermissionsResult>;
+/**
+ * Check if a permission set includes a specific permission.
+ *
+ * Pure function — no API call. Use with permissions from JWT claims
+ * (org_permissions) or from getMemberPermissions().
+ *
+ * @example
+ * ```typescript
+ * const permissions = ['org:members:read', 'payroll:view']
+ * hasPermission(permissions, 'payroll:view')    // true
+ * hasPermission(permissions, 'payroll:approve') // false
+ * ```
+ */
+declare function hasPermission(permissions: string[], required: string): boolean;
+/**
+ * Check if a permission set includes ANY of the required permissions.
+ *
+ * Pure function — no API call. Returns true if at least one of the
+ * required permissions is present.
+ *
+ * @example
+ * ```typescript
+ * const permissions = ['org:members:read', 'payroll:view']
+ * hasAnyPermission(permissions, ['payroll:view', 'payroll:approve']) // true
+ * hasAnyPermission(permissions, ['admin:full', 'super:admin'])       // false
+ * ```
+ */
+declare function hasAnyPermission(permissions: string[], required: string[]): boolean;
+/**
+ * Check if a permission set includes ALL of the required permissions.
+ *
+ * Pure function — no API call. Returns true only if every required
+ * permission is present.
+ *
+ * @example
+ * ```typescript
+ * const permissions = ['org:members:read', 'payroll:view', 'payroll:approve']
+ * hasAllPermissions(permissions, ['payroll:view', 'payroll:approve']) // true
+ * hasAllPermissions(permissions, ['payroll:view', 'admin:full'])      // false
+ * ```
+ */
+declare function hasAllPermissions(permissions: string[], required: string[]): boolean;
+
+/**
+ * Role Functions
+ *
+ * Pure functions for role management — no hidden state.
+ * Each function takes config as the first parameter.
+ *
+ * Uses REST API at /roles/* for project-scoped operations.
+ * Uses REST API at /orgs/{orgId}/members/{memberId}/assign-role for assignment.
+ *
+ * Types are self-contained (not dependent on generated OpenAPI spec) because
+ * the RBAC routes were added after the last spec generation.
+ */
+
+/**
+ * A role definition within a project.
+ *
+ * Roles bundle permissions into named groups that can be assigned to
+ * organization members (e.g. "HR Manager", "Payroll Admin").
+ */
+interface Role {
+    /** Prefixed role ID (e.g. "role_xxx") */
+    id: string;
+    /** Unique key within the project (e.g. "hr_manager") */
+    key: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description: string | null;
+    /** Whether this is a system-defined role (metadata immutable) */
+    isSystem: boolean;
+    /** Whether this role is automatically assigned to new org members */
+    isDefault: boolean;
+    /** Display order (lower = higher priority) */
+    sortOrder: number;
+    /** Permission keys assigned to this role */
+    permissions: string[];
+    /** ISO 8601 creation timestamp */
+    createdAt: string;
+    /** ISO 8601 update timestamp (present on roles route response) */
+    updatedAt?: string;
+}
+/**
+ * Input for creating a custom role.
+ */
+interface CreateRoleInput {
+    /** Unique key — lowercase alphanumeric with underscores (e.g. "hr_manager") */
+    key: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Permission keys to assign to this role */
+    permissions?: string[];
+    /** Whether to auto-assign to new org members */
+    isDefault?: boolean;
+    /** Display order (lower = higher priority) */
+    sortOrder?: number;
+}
+/**
+ * Input for updating an existing role.
+ *
+ * System role metadata (name, description) is immutable, but their
+ * permissions can be changed.
+ */
+interface UpdateRoleInput {
+    /** Human-readable name (ignored for system roles) */
+    name?: string;
+    /** Description (ignored for system roles) */
+    description?: string | null;
+    /** Permission keys to assign (replaces existing) */
+    permissions?: string[];
+    /** Whether to auto-assign to new org members */
+    isDefault?: boolean;
+    /** Display order */
+    sortOrder?: number;
+}
+/**
+ * List all roles for the current project.
+ *
+ * Returns both system-defined and custom roles, each with their
+ * assigned permission keys. Requires a secret key (server-side only).
+ *
+ * @example
+ * ```typescript
+ * const { roles } = await listRoles(config)
+ * for (const role of roles) {
+ *   console.log(`${role.name}: ${role.permissions.join(', ')}`)
+ * }
+ * ```
+ */
+declare function listRoles(config: SylphxConfig): Promise<{
+    roles: Role[];
+}>;
+/**
+ * Get a single role by key, including its assigned permission keys.
+ *
+ * Requires a secret key (server-side only).
+ *
+ * @example
+ * ```typescript
+ * const { role } = await getRole(config, 'hr_manager')
+ * console.log(role.permissions)
+ * // ['org:members:read', 'payroll:view', 'payroll:approve']
+ * ```
+ */
+declare function getRole(config: SylphxConfig, roleKey: string): Promise<{
+    role: Role;
+}>;
+/**
+ * Create a custom role with optional permission assignments.
+ *
+ * Role keys must be lowercase alphanumeric with underscores
+ * (e.g. "hr_manager", "payroll_admin").
+ * Requires a secret key (server-side only).
+ *
+ * @example
+ * ```typescript
+ * const { role } = await createRole(config, {
+ *   key: 'hr_manager',
+ *   name: 'HR Manager',
+ *   description: 'Can manage employees and approve leave',
+ *   permissions: ['org:members:read', 'leave:approve', 'payroll:view'],
+ * })
+ * ```
+ */
+declare function createRole(config: SylphxConfig, input: CreateRoleInput): Promise<{
+    role: Role;
+}>;
+/**
+ * Update a role's metadata and/or permission assignments.
+ *
+ * System role metadata (name, description) is immutable, but their
+ * permissions can be changed. Passing `permissions` replaces the
+ * entire permission set for the role.
+ * Requires a secret key (server-side only).
+ *
+ * @example
+ * ```typescript
+ * const { role } = await updateRole(config, 'hr_manager', {
+ *   permissions: ['org:members:read', 'org:members:manage', 'leave:approve'],
+ * })
+ * ```
+ */
+declare function updateRole(config: SylphxConfig, roleKey: string, input: UpdateRoleInput): Promise<{
+    role: Role;
+}>;
+/**
+ * Delete a custom role by key.
+ *
+ * System roles cannot be deleted. Roles with active member assignments
+ * cannot be deleted — reassign members first.
+ * Requires a secret key (server-side only).
+ *
+ * @example
+ * ```typescript
+ * const { success } = await deleteRole(config, 'hr_manager')
+ * ```
+ */
+declare function deleteRole(config: SylphxConfig, roleKey: string): Promise<{
+    success: boolean;
+}>;
+/**
+ * Assign an RBAC role to an organization member.
+ *
+ * Replaces any existing role assignment (single-role mode).
+ * Requires admin access to the organization.
+ *
+ * @example
+ * ```typescript
+ * const { success } = await assignMemberRole(config, 'my-org', 'usr_abc123', 'hr_manager')
+ * ```
+ */
+declare function assignMemberRole(config: SylphxConfig, orgIdOrSlug: string, memberId: string, roleKey: string): Promise<{
+    success: boolean;
+}>;
+
 /**
  * Secrets SDK
  *
@@ -25330,6 +25754,21 @@ interface SandboxOptions {
     };
     /** Environment variables injected into the sandbox container */
     env?: Record<string, string>;
+    /**
+     * Shared volume mounts from org-level managed volumes.
+     * Requires ReadWriteMany volumes (CephFS). Multiple sandboxes can mount
+     * the same volume for shared filesystem access.
+     */
+    volumeMounts?: Array<{
+        /** Volume resource ID (from `sylphx volumes list`) */
+        volumeId: string;
+        /** Absolute path inside the container (e.g. "/shared") */
+        mountPath: string;
+        /** Optional sub-path within the volume */
+        subPath?: string;
+        /** Read-only mount (default: false) */
+        readOnly?: boolean;
+    }>;
 }
 /** SSE event emitted by sandbox.exec() */
 type ExecEvent = {
@@ -25368,6 +25807,75 @@ interface ExecOptions {
     timeout?: number;
     stdin?: string;
 }
+interface ProcessStartOptions {
+    /** Command + args (e.g. ['npm', 'install']) */
+    command: string[];
+    /** Working directory */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Hard timeout in seconds (0 = no timeout) */
+    timeoutSeconds?: number;
+    /** Open stdin pipe for writing */
+    stdin?: boolean;
+}
+interface ProcessInfo {
+    id: string;
+    pid: number;
+    command: string[];
+    cwd: string;
+    status: 'running' | 'exited' | 'killed' | 'timeout';
+    exitCode: number | null;
+    signal: string | null;
+    startedAt: string;
+    exitedAt: string | null;
+    durationMs: number | null;
+    stdout: string;
+    stderr: string;
+}
+interface ProcessSummary {
+    id: string;
+    pid: number;
+    command: string[];
+    status: 'running' | 'exited' | 'killed' | 'timeout';
+    exitCode: number | null;
+    startedAt: string;
+    exitedAt: string | null;
+    durationMs: number | null;
+}
+/** SSE event from a process stream */
+type ProcessEvent = {
+    type: 'stdout';
+    pid: number;
+    data: string;
+} | {
+    type: 'stderr';
+    pid: number;
+    data: string;
+} | {
+    type: 'exit';
+    pid: number;
+    exitCode: number;
+};
+interface WatchOptions {
+    /** Path to watch (relative to /workspace or absolute) */
+    path: string;
+    /** Watch subdirectories recursively (default: true) */
+    recursive?: boolean;
+    /** Additional patterns to ignore */
+    ignore?: string[];
+}
+interface WatchEntry {
+    path: string;
+    recursive: boolean;
+    createdAt: string;
+}
+/** File change event delivered via SSE /events stream */
+interface FileEvent {
+    type: 'file';
+    path: string;
+    event: 'created' | 'modified' | 'deleted';
+}
 interface SandboxRecord {
     id: string;
     status: 'starting' | 'running' | 'idle' | 'terminated' | 'error';
@@ -25397,6 +25905,46 @@ declare class SandboxFiles {
     /** List files in a directory. */
     list(path?: string): Promise<string[]>;
 }
+declare class SandboxProcesses {
+    private readonly endpoint;
+    private readonly token;
+    constructor(endpoint: string, token: string);
+    private authHeader;
+    /** Spawn a new tracked process. Returns processId + pid immediately. */
+    start(opts: ProcessStartOptions): Promise<{
+        id: string;
+        pid: number;
+    }>;
+    /** List all tracked processes. */
+    list(): Promise<ProcessSummary[]>;
+    /** Get full process info including buffered output. */
+    get(processId: string): Promise<ProcessInfo>;
+    /** Send a signal to a process. */
+    kill(processId: string, signal?: string): Promise<void>;
+    /** Write to process stdin. */
+    writeStdin(processId: string, data: string): Promise<void>;
+    /**
+     * Wait for a process to complete and return its final info.
+     * Polls every 500ms until status is no longer 'running'.
+     *
+     * For real-time output, use stream() instead.
+     */
+    wait(processId: string, timeoutMs?: number): Promise<ProcessInfo>;
+    /** Stream process output as async iterable SSE events. */
+    stream(processId: string): AsyncGenerator<ProcessEvent>;
+}
+declare class SandboxWatch {
+    private readonly endpoint;
+    private readonly token;
+    constructor(endpoint: string, token: string);
+    private authHeader;
+    /** Start watching a path. Events delivered via sandbox.events() SSE stream. */
+    add(opts: WatchOptions): Promise<WatchEntry>;
+    /** List active watches. */
+    list(): Promise<WatchEntry[]>;
+    /** Stop watching a path. */
+    remove(path: string): Promise<void>;
+}
 declare class SandboxClient {
     readonly id: string;
     private readonly config;
@@ -25406,6 +25954,10 @@ declare class SandboxClient {
     readonly token: string | null;
     /** File operations (direct to exec-server) */
     readonly files: SandboxFiles | null;
+    /** Concurrent process management (direct to exec-server) */
+    readonly processes: SandboxProcesses | null;
+    /** Filesystem watch management (direct to exec-server) */
+    readonly watch: SandboxWatch | null;
     private constructor();
     /**
      * Create a new sandbox.
@@ -25423,10 +25975,21 @@ declare class SandboxClient {
     getStatus(): Promise<SandboxRecord>;
     terminate(): Promise<void>;
     /**
-     * Execute a command and stream output as async iterable events.
+     * Execute a command and stream output as async iterable SSE events.
+     *
+     * **Stateless mode**: each exec() call runs in an isolated bash invocation.
+     * Shell state (CWD changes, exported env vars, functions) is NOT preserved
+     * between calls.
      *
-     * Uses Server-Sent Events (SSE) for real-time stdout/stderr streaming.
-     * Communicates DIRECTLY with exec-server (Platform not in data path).
+     * For state-preserving execution (CWD, env), use `run()` which runs in the
+     * persistent active shell and returns the result once complete.
+     *
+     * For streaming + state-preserving (advanced), combine `sandbox.events()` with `run()`:
+     * ```typescript
+     * const eventStream = sandbox.events({ type: 'stdout' })
+     * sandbox.run(['npm', 'install']) // don't await yet
+     * for await (const ev of eventStream) { ... }
+     * ```
      *
      * @example
      * ```typescript
@@ -25444,6 +26007,24 @@ declare class SandboxClient {
      * For long-running commands, prefer exec() to stream output incrementally.
      */
     run(command: string[], options?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Subscribe to the unified event stream (SSE).
+     *
+     * Receives all sandbox events: stdout, stderr, exit, port, file, shell, resource.
+     * Filter by type/pid/shellId using query params.
+     *
+     * @example
+     * ```typescript
+     * for await (const event of sandbox.events({ type: 'file' })) {
+     *   console.log('File changed:', event.path, event.event)
+     * }
+     * ```
+     */
+    events(filter?: {
+        type?: 'stdout' | 'stderr' | 'exit' | 'port' | 'file' | 'shell' | 'resource';
+        pid?: number;
+        shellId?: string;
+    }): AsyncGenerator<Record<string, unknown>>;
     /**
      * Open an interactive PTY session (WebSocket).
      *
@@ -25463,11 +26044,11 @@ declare class SandboxClient {
 }
 
 /**
- * Workers Client
+ * Runs Client (ADR-040, formerly Workers)
  *
  * Fire-and-forget batch compute API (Modal-style run-to-completion jobs).
  *
- * Workers are ephemeral K8s Jobs that run to completion. Use them for:
+ * Runs are ephemeral K8s Jobs that run to completion. Use them for:
  * - ML training folds (walk-forward cross-validation)
  * - Data processing pipelines
  * - Batch inference
@@ -25477,11 +26058,11 @@ declare class SandboxClient {
  *
  * ### Single worker
  * ```typescript
- * import { createConfig, WorkersClient } from '@sylphx/sdk'
+ * import { createConfig, RunsClient } from '@sylphx/sdk'
  *
  * const config = createConfig({ secretKey: process.env.SYLPHX_SECRET_KEY!, ref: 'my-project' })
  *
- * const worker = await WorkersClient.run(config, {
+ * const run = await RunsClient.create(config, {
  *   image: 'registry.sylphx.com/sylphx/my-trainer:abc123',
  *   command: ['python', 'train.py', '--fold', '0'],
  *   resources: { requests: { cpu: '4', memory: '8Gi' } },
@@ -25497,7 +26078,7 @@ declare class SandboxClient {
  * ```typescript
  * const workers = await Promise.all(
  *   folds.map((fold) =>
- *     WorkersClient.run(config, {
+ *     RunsClient.create(config, {
  *       image: 'registry.sylphx.com/sylphx/trainer:abc123',
  *       command: ['python', 'train.py', '--fold', String(fold.id)],
  *       env: { FOLD_ID: String(fold.id), DATABASE_URL: process.env.DATABASE_URL! },
@@ -25525,8 +26106,8 @@ declare class SandboxClient {
  * @module
  */
 
-type WorkerStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'timeout';
-interface WorkerVolumeMount {
+type RunStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'timeout';
+interface RunVolumeMount {
     /** UUID of the volumeResource to mount (must belong to this org) */
     volumeId: string;
     /** Absolute mount path inside the container (e.g. '/cache') */
@@ -25536,7 +26117,7 @@ interface WorkerVolumeMount {
     /** Mount as read-only (default: false) */
     readOnly?: boolean;
 }
-interface WorkerResourceSpec {
+interface RunResourceSpec {
     requests?: {
         /** CPU request (e.g. '500m', '2', '4') */
         cpu?: string;
@@ -25550,7 +26131,7 @@ interface WorkerResourceSpec {
         memory?: string;
     };
 }
-interface RunWorkerOptions {
+interface CreateRunOptions {
     /**
      * Docker image to run (must be from registry.sylphx.com).
      *
@@ -25573,7 +26154,7 @@ interface RunWorkerOptions {
      * CPU/memory resource spec.
      * Defaults: { requests: { cpu: '500m', memory: '512Mi' }, limits: { cpu: '2', memory: '2Gi' } }
      */
-    resources?: WorkerResourceSpec;
+    resources?: RunResourceSpec;
     /**
      * Hard timeout in seconds (default: 3600 = 1 hour, max: 86400 = 24 hours).
      * K8s terminates the Job when the deadline is reached (status: 'timeout').
@@ -25583,13 +26164,13 @@ interface RunWorkerOptions {
      * Volume mounts from org-level volumeResources.
      * ReadWriteMany volumes (rook-cephfs) allow concurrent access by multiple parallel workers.
      */
-    volumeMounts?: WorkerVolumeMount[];
+    volumeMounts?: RunVolumeMount[];
 }
-interface WorkerRun {
+interface Run {
     /** Worker run ID (e.g. 'worker_Vh3kJ9mNpQ2wXsL1') */
     id: string;
     /** Current lifecycle status */
-    status: WorkerStatus;
+    status: RunStatus;
     /** Docker image */
     image: string;
     /** Command being executed */
@@ -25597,11 +26178,11 @@ interface WorkerRun {
     /** Environment variables */
     env: Record<string, string> | null;
     /** Resource spec */
-    resources: WorkerResourceSpec | null;
+    resources: RunResourceSpec | null;
     /** Hard timeout in seconds */
     timeoutSeconds: number;
     /** Volume mounts */
-    volumeMounts: WorkerVolumeMount[] | null;
+    volumeMounts: RunVolumeMount[] | null;
     /** Exit code (only when succeeded or failed) */
     exitCode: number | null;
     /** Captured stdout (up to 1 MiB) */
@@ -25621,11 +26202,11 @@ interface WorkerRun {
     /** Last update timestamp */
     updatedAt: string;
 }
-interface WorkerResult {
+interface RunResult {
     /** Exit code (0 = success) */
     exitCode: number | null;
     /** Status at completion */
-    status: WorkerStatus;
+    status: RunStatus;
     /** Captured stdout */
     stdout: string | null;
     /** Captured stderr */
@@ -25635,7 +26216,7 @@ interface WorkerResult {
     /** Wall-clock duration in milliseconds */
     durationMs: number | null;
 }
-interface WorkerLogsResult {
+interface RunLogsResult {
     /** Captured stdout (up to 1 MiB) */
     stdout: string;
     /** Captured stderr (up to 1 MiB) */
@@ -25643,14 +26224,14 @@ interface WorkerLogsResult {
     /** Whether logs are still being captured (worker is running) */
     live: boolean;
 }
-interface ListWorkersOptions {
+interface ListRunsOptions {
     /** Filter by status */
-    status?: WorkerStatus;
+    status?: RunStatus;
 }
 /** OpenAI/Stripe-style list response */
-interface ListWorkersResult {
+interface ListRunsResult {
     object: 'list';
-    data: WorkerRun[];
+    data: Run[];
     /** True if there are more results (limit was hit) */
     has_more: boolean;
 }
@@ -25658,20 +26239,20 @@ interface ListWorkersResult {
  * Handle to a running (or completed) worker.
  * Use `.wait()` to poll until completion, `.logs()` to stream logs, `.cancel()` to abort.
  */
-declare class WorkerHandle {
+declare class RunHandle {
     readonly id: string;
     private readonly config;
     constructor(id: string, config: SylphxConfig);
     /**
      * Get the current status of this worker.
      */
-    status(): Promise<WorkerRun>;
+    status(): Promise<Run>;
     /**
      * Poll the worker until it reaches a terminal state (succeeded, failed, cancelled, timeout).
      *
      * @param options.pollIntervalMs - How often to poll in ms (default: 3000)
      * @param options.timeoutMs - Max time to wait before throwing (default: 7_200_000 = 2h)
-     * @returns WorkerResult with exit code, status, stdout/stderr
+     * @returns RunResult with exit code, status, stdout/stderr
      * @throws Error if waitTimeout is exceeded
      *
      * @example
@@ -25685,7 +26266,7 @@ declare class WorkerHandle {
     wait(options?: {
         pollIntervalMs?: number;
         timeoutMs?: number;
-    }): Promise<WorkerResult>;
+    }): Promise<RunResult>;
     /**
      * Fetch captured logs for this worker.
      *
@@ -25699,7 +26280,7 @@ declare class WorkerHandle {
      * if (live) console.log('(worker still running, logs may be incomplete)')
      * ```
      */
-    logs(): Promise<WorkerLogsResult>;
+    logs(): Promise<RunLogsResult>;
     /**
      * Cancel this worker.
      *
@@ -25717,13 +26298,75 @@ declare class WorkerHandle {
  * const config = createConfig({ secretKey: process.env.SYLPHX_SECRET_KEY!, ref: 'my-project' })
  *
  * // Run a worker and wait for completion
- * const result = await WorkersClient.run(config, { ... }).then(w => w.wait())
+ * const result = await RunsClient.create(config, { ... }).then(w => w.wait())
  *
  * // Run N workers in parallel, wait for all
- * const handles = await Promise.all(folds.map(fold => WorkersClient.run(config, { ... })))
+ * const handles = await Promise.all(folds.map(fold => RunsClient.create(config, { ... })))
  * const results = await Promise.all(handles.map(h => h.wait()))
  * ```
  */
+declare const RunsClient: {
+    /**
+     * Spawn a new worker (K8s Job) and return a handle.
+     *
+     * The Job is created immediately and starts pulling the image.
+     * Use the returned handle to `.wait()` for completion or `.cancel()`.
+     *
+     * @example
+     * ```typescript
+     * const run = await RunsClient.create(config, {
+     *   image: 'registry.sylphx.com/sylphx/trainer:abc123',
+     *   command: ['python', 'train.py', '--fold', '3'],
+     *   resources: { requests: { cpu: '4', memory: '16Gi' } },
+     *   volumeMounts: [{ volumeId: cacheVolumeId, mountPath: '/cache' }],
+     * })
+     * const result = await worker.wait()
+     * ```
+     */
+    run(config: SylphxConfig, options: CreateRunOptions): Promise<RunHandle>;
+    /**
+     * Get a RunHandle for an existing run by ID.
+     *
+     * Useful for resuming monitoring across requests.
+     *
+     * @example
+     * ```typescript
+     * // Store the worker ID, retrieve later
+     * const handle = RunsClient.fromId(config, storedWorkerId)
+     * const result = await handle.wait()
+     * ```
+     */
+    fromId(config: SylphxConfig, workerId: string): RunHandle;
+    /**
+     * List worker runs for this environment.
+     *
+     * @example
+     * ```typescript
+     * const { workers } = await RunsClient.list(config, { status: 'running' })
+     * console.log(`${workers.length} workers currently running`)
+     * ```
+     */
+    list(config: SylphxConfig, options?: ListRunsOptions): Promise<ListRunsResult>;
+    /**
+     * Spawn a worker and wait for it to complete in one call.
+     *
+     * Equivalent to `(await RunsClient.create(config, options)).wait(waitOptions)`.
+     *
+     * @example
+     * ```typescript
+     * const result = await RunsClient.runAndWait(config, {
+     *   image: 'registry.sylphx.com/sylphx/process:abc',
+     *   command: ['node', 'dist/process.js'],
+     * })
+     * if (result.exitCode !== 0) throw new Error(result.errorMessage ?? 'worker failed')
+     * ```
+     */
+    runAndWait(config: SylphxConfig, options: CreateRunOptions, waitOptions?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<RunResult>;
+};
+/** @deprecated Use RunsClient */
 declare const WorkersClient: {
     /**
      * Spawn a new worker (K8s Job) and return a handle.
@@ -25733,7 +26376,7 @@ declare const WorkersClient: {
      *
      * @example
      * ```typescript
-     * const worker = await WorkersClient.run(config, {
+     * const run = await RunsClient.create(config, {
      *   image: 'registry.sylphx.com/sylphx/trainer:abc123',
      *   command: ['python', 'train.py', '--fold', '3'],
      *   resources: { requests: { cpu: '4', memory: '16Gi' } },
@@ -25742,48 +26385,203 @@ declare const WorkersClient: {
      * const result = await worker.wait()
      * ```
      */
-    run(config: SylphxConfig, options: RunWorkerOptions): Promise<WorkerHandle>;
+    run(config: SylphxConfig, options: CreateRunOptions): Promise<RunHandle>;
     /**
-     * Get a WorkerHandle for an existing run by ID.
+     * Get a RunHandle for an existing run by ID.
      *
      * Useful for resuming monitoring across requests.
      *
      * @example
      * ```typescript
      * // Store the worker ID, retrieve later
-     * const handle = WorkersClient.fromId(config, storedWorkerId)
+     * const handle = RunsClient.fromId(config, storedWorkerId)
      * const result = await handle.wait()
      * ```
      */
-    fromId(config: SylphxConfig, workerId: string): WorkerHandle;
+    fromId(config: SylphxConfig, workerId: string): RunHandle;
     /**
      * List worker runs for this environment.
      *
      * @example
      * ```typescript
-     * const { workers } = await WorkersClient.list(config, { status: 'running' })
+     * const { workers } = await RunsClient.list(config, { status: 'running' })
      * console.log(`${workers.length} workers currently running`)
      * ```
      */
-    list(config: SylphxConfig, options?: ListWorkersOptions): Promise<ListWorkersResult>;
+    list(config: SylphxConfig, options?: ListRunsOptions): Promise<ListRunsResult>;
     /**
      * Spawn a worker and wait for it to complete in one call.
      *
-     * Equivalent to `(await WorkersClient.run(config, options)).wait(waitOptions)`.
+     * Equivalent to `(await RunsClient.create(config, options)).wait(waitOptions)`.
      *
      * @example
      * ```typescript
-     * const result = await WorkersClient.runAndWait(config, {
+     * const result = await RunsClient.runAndWait(config, {
      *   image: 'registry.sylphx.com/sylphx/process:abc',
      *   command: ['node', 'dist/process.js'],
      * })
      * if (result.exitCode !== 0) throw new Error(result.errorMessage ?? 'worker failed')
      * ```
      */
-    runAndWait(config: SylphxConfig, options: RunWorkerOptions, waitOptions?: {
+    runAndWait(config: SylphxConfig, options: CreateRunOptions, waitOptions?: {
         pollIntervalMs?: number;
         timeoutMs?: number;
-    }): Promise<WorkerResult>;
+    }): Promise<RunResult>;
 };
 
-export { ACHIEVEMENT_TIER_CONFIG, type AIListModelsOptions, type AIListModelsResponse, type AIMessage, type AIMessageRole, type AIModel, type AIModelInfo, type AIModelsResponse, type AIProvider, type AIRateLimitInfo, type AIRateLimitResponse, type AIRequestType, type AIStreamChunk, type AITool, type AIToolCall, type AIUsageResponse, type AIUsageStats, type AccessTokenPayload, type AchievementCategory, type AchievementCriteria, type AchievementCriterion, type AchievementDefinition, type AchievementTier, type AchievementType, type AchievementUnlockEvent, type AdminUser, AuthenticationError, AuthorizationError, type BalanceResponse, type BatchEvent, type BatchIndexInput, type BatchIndexResult, type Breadcrumb, type BuildLog, type BuildLogHistoryResponse, type CaptureExceptionRequest, type CaptureMessageRequest, type ChatCompletionInput, type ChatCompletionResponse, type ChatInput, type ChatMessage, type ChatResult, type ChatStreamChunk, type CheckoutRequest, type CheckoutResponse, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitState, type CommandResult, type ConsentCategory, type ConsentHistoryEntry, type ConsentHistoryResult, type ConsentPurposeDefaults, type ConsentType, type ContentPart, type CreateOrgInput, type CriteriaOperator, type CronInput, type CronSchedule, type DatabaseConnectionInfo, type DatabaseStatus, type DatabaseStatusInfo, type DebugCategory, type DeduplicationConfig, type DeleteDocumentInput, type DeployHistoryResponse, type DeployInfo, type DeployStatus, type DynamicRestClient, ERROR_CODE_STATUS, type EmbedInput, type EmbedResult, type EmbeddingInput, type EmbeddingResponse, type LeaderboardEntry as EngagementLeaderboardEntry, type LeaderboardResult as EngagementLeaderboardResult, type EnvVar, type ErrorCode, type ErrorResponse, type ExceptionFrame, type ExceptionValue, type ExecOptions, type FacetsResponse, type FileInfo, type FileUploadOptions, type FlagContext, type FlagResult, type GetConsentHistoryInput, type GetConsentsInput, type GetFacetsInput, type GetSecretInput, type GetSecretResult, type GetSecretsInput, type GetSecretsResult, type IdentifyInput, type IndexDocumentInput, type IndexDocumentResult, type InviteMemberInput, type InviteUserRequest, type InviteUserResponse, type KvExpireRequest, type KvHgetRequest, type KvHgetallRequest, type KvHsetRequest, type KvIncrRequest, type KvLpushRequest, type KvLrangeRequest, type KvMgetRequest, type KvMsetRequest, type KvRateLimitRequest, type KvRateLimitResult, type KvScanOptions, type KvScanResult, type KvSetOptions, type KvSetRequest, type KvZMember, type KvZaddRequest, type KvZrangeRequest, type LeaderboardAggregation, type LeaderboardDefinition, type LeaderboardEntry$1 as LeaderboardEntry, type LeaderboardOptions, type LeaderboardQueryOptions, type LeaderboardResetPeriod, type LeaderboardResult$1 as LeaderboardResult, type LeaderboardSortDirection, type LinkAnonymousConsentsInput, type ListScheduledEmailsOptions, type ListSecretKeysInput, type ListUsersOptions, type ListUsersResult, type ListWorkersOptions, type ListWorkersResult, type LoginHistoryEntry, type LoginRequest, type LoginResponse, type MeResponse, type MonitoringResponse, type MonitoringSeverity, type NativeStepContext, type NativeTaskDefinition, type TaskRunStatus as NativeTaskRunStatus, NetworkError, NotFoundError, type OrgRole, type OrgTokenPayload, type Organization, type OrganizationInvitation, type OrganizationMember, type OrganizationMembership, type PageInput, type PaginatedResponse, type PaginationInput, type ParsedKey, type Plan, type PortalRequest, type PortalResponse, type PushNotification, type PushNotificationPayload, type PushServiceWorkerConfig, type PushSubscription, RETRYABLE_CODES, RateLimitError, type RealtimeEmitRequest, type RealtimeEmitResponse, type RealtimeHistoryRequest, type RealtimeHistoryResponse, type RecordActivityInput, type RecordActivityResult, type RedeemReferralInput, type RedeemResult, type ReferralCode, type ReferralStats, type RegisterInput, type RegisterRequest, type RegisterResponse, type RestClient, type RestClientConfig, type RestDynamicConfig, type paths as RestPaths, type RetryConfig, type RevokeTokenOptions, type RollbackDeployRequest, type RunWorkerOptions, SandboxClient, type SandboxFile, type SandboxOptions, type ScheduleEmailOptions, type ScheduledEmail, type ScheduledEmailStats, type ScheduledEmailsResult, type SearchInput, type SearchResponse, type SearchResultItem, type SearchStatsResult, type SearchType, type SecretKeyInfo, type SecuritySettings, type SendEmailOptions, type SendResult, type SendTemplatedEmailOptions, type SendToUserOptions, type SessionResult, type SetConsentsInput, type SetEnvVarRequest, type SignedUrlOptions, type SignedUrlResult, StepCompleteSignal, StepSleepSignal, type StreakDefinition, type StreakFrequency, type StreakState, type StreamMessage, type SubmitScoreInput, type SubmitScoreResult, type Subscription, type SuccessResponse, type SylphxConfig, type SylphxConfigInput, SylphxError, type SylphxErrorCode, type SylphxErrorOptions, type TaskInput, type TaskResult, type TaskStatus, type TextCompletionInput, type TextCompletionResponse, TimeoutError, type TokenIntrospectionResult, type TokenResponse, type Tool, type ToolCall, type TrackClickInput, type TrackInput, type TriggerDeployRequest, type TwoFactorVerifyRequest, type UpdateOrgInput, type UploadProgressEvent, type UploadResult, type UpsertDocumentInput, type UpsertDocumentResult, type UsageResponse, type User, type UserAchievement, type UserConsent, type UserProfile, ValidationError, type VisionInput, type WebhookConfig, type WebhookConfigUpdate, type WebhookDeliveriesResult, type WebhookDelivery, type WebhookStats, WorkerHandle, type WorkerLogsResult, type WorkerResourceSpec, type WorkerResult, type WorkerRun, type WorkerStatus, type WorkerVolumeMount, WorkersClient, acceptAllConsents, acceptOrganizationInvitation, batchIndex, canDeleteOrganization, canManageMembers, canManageSettings, cancelScheduledEmail, cancelTask, captureException, captureExceptionRaw, captureMessage, chat, chatStream, checkFlag, complete, createCheckout, createConfig, createCron, createDynamicRestClient, createOrganization, createPortalSession, createRestClient, createServiceWorkerScript, createStepContext, createTasksHandler, createTracker, debugError, debugLog, debugTimer, debugWarn, declineOptionalConsents, deleteCron, deleteDocument, deleteEnvVar, deleteFile, deleteOrganization, deleteUser, disableDebug, embed, enableDebug, exponentialBackoff, extendedSignUp, forgotPassword, generateAnonymousId, getAchievement, getAchievementPoints, getAchievements, getAllFlags, getAllSecrets, getAllStreaks, getBillingBalance, getBillingUsage, getBuildLogHistory, getCircuitBreakerState, getConsentHistory, getConsentTypes, getDatabaseConnectionString, getDatabaseStatus, getDebugMode, getDeployHistory, getDeployStatus, getErrorCode, getErrorMessage, getFacets, getFileInfo, getFileUrl, getFlagPayload, getFlags, getLeaderboard, getMyReferralCode, getOrganization, getOrganizationInvitations, getOrganizationMembers, getOrganizations, getPlans, getPushPreferences, getRealtimeHistory, getReferralLeaderboard, getReferralStats, getRestErrorMessage, getScheduledEmail, getScheduledEmailStats, getSearchStats, getSecret, getSecrets, getSession, getSignedUrl, getStreak, getSubscription, getTask, getUser, getUserByEmail, getUserConsents, getUserLeaderboardRank, getVariant, getWebhookConfig, getWebhookDeliveries, getWebhookDelivery, getWebhookStats, hasConsent, hasError, hasRole, hasSecret, identify, incrementAchievementProgress, indexDocument, initPushServiceWorker, installGlobalDebugHelpers, introspectToken, inviteOrganizationMember, inviteUser, isEmailConfigured, isEnabled, isRetryableError, isSylphxError, kvDelete, kvExists, kvExpire, kvGet, kvGetJSON, kvHget, kvHgetall, kvHset, kvIncr, kvLpush, kvLrange, kvMget, kvMset, kvRateLimit, kvScan, kvSet, kvSetJSON, kvZadd, kvZrange, leaveOrganization, linkAnonymousConsents, listEnvVars, listScheduledEmails, listSecretKeys, listTasks, listUsers, page, parseKey, pauseCron, realtimeEmit, recordStreakActivity, recoverStreak, redeemReferralCode, refreshToken, regenerateReferralCode, registerPush, registerPushServiceWorker, removeOrganizationMember, replayWebhookDelivery, rescheduleEmail, resetCircuitBreaker, resetDebugModeCache, resetPassword, resumeCron, revokeAllTokens, revokeOrganizationInvitation, revokeToken, rollbackDeploy, scheduleEmail, scheduleTask, search, sendEmail, sendEmailToUser, sendPush, sendTemplatedEmail, setConsents, setEnvVar, signIn, signOut, signUp, streamToString, submitScore, suspendUser, switchOrg, toSylphxError, track, trackBatch, trackClick, triggerDeploy, unlockAchievement, unregisterPush, updateOrganization, updateOrganizationMemberRole, updatePushPreferences, updateUser, updateUserMetadata, updateWebhookConfig, uploadAvatar, uploadFile, upsertDocument, verifyEmail, verifySignature as verifyTaskSignature, verifyTwoFactor, withToken };
+/**
+ * Triggers Client (ADR-040)
+ *
+ * Unified scheduling + event dispatch API.
+ * Create cron schedules and event triggers that dispatch to Tasks, Runs, or HTTP URLs.
+ *
+ * ## Usage
+ *
+ * ### Cron → Task
+ * ```typescript
+ * import { createConfig, TriggersClient } from '@sylphx/sdk'
+ * const config = createConfig({ secretKey: process.env.SYLPHX_SECRET_KEY!, ref: 'my-project' })
+ *
+ * const trigger = await TriggersClient.create(config, {
+ *   name: 'daily-cleanup',
+ *   source: { type: 'cron', expression: '0 2 * * *' },
+ *   target: { type: 'task', taskName: 'daily-cleanup' },
+ * })
+ * ```
+ *
+ * ### Event → Task (fires when event is published via publishEvent)
+ * ```typescript
+ * const trigger = await TriggersClient.create(config, {
+ *   name: 'welcome-email-on-signup',
+ *   source: { type: 'event', eventName: 'user.signup' },
+ *   target: { type: 'task', taskName: 'send-welcome-email' },
+ * })
+ * // Publish from your app:
+ * await TriggersClient.publishEvent(config, 'user.signup', { userId: '123' })
+ * ```
+ *
+ * ### Cron → HTTP URL (any language, no code required)
+ * ```typescript
+ * const trigger = await TriggersClient.create(config, {
+ *   name: 'nightly-backup',
+ *   source: { type: 'cron', expression: '0 3 * * *' },
+ *   target: { type: 'http', url: 'https://myapp.com/api/backup', payload: { type: 'full' } },
+ * })
+ * ```
+ */
+
+type TriggerTargetType = 'task' | 'run' | 'http';
+type TriggerSourceType = 'cron' | 'event';
+type TriggerStatus = 'active' | 'paused' | 'deleted';
+interface TaskTarget {
+    type: 'task';
+    taskName: string;
+    handlerPath?: string;
+    payload?: Record<string, unknown>;
+}
+interface HttpTarget {
+    type: 'http';
+    url: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    headers?: Record<string, string>;
+    payload?: Record<string, unknown>;
+}
+interface RunTarget {
+    type: 'run';
+    image: string;
+    command: string[];
+    resources?: {
+        cpu?: string;
+        memory?: string;
+    };
+}
+type TriggerTarget = TaskTarget | HttpTarget | RunTarget;
+interface CronSource {
+    type: 'cron';
+    expression: string;
+}
+interface EventSource {
+    type: 'event';
+    /** The event name to listen for. e.g. 'user.signup', 'order.paid' */
+    eventName: string;
+}
+type TriggerSource = CronSource | EventSource;
+interface CreateTriggerOptions {
+    name?: string;
+    source: TriggerSource;
+    target: TriggerTarget;
+    paused?: boolean;
+    /** Idempotency key — prevents duplicate trigger creation per project+environment */
+    idempotencyKey?: string;
+}
+interface UpdateTriggerOptions {
+    name?: string;
+    source?: TriggerSource;
+    paused?: boolean;
+}
+interface Trigger {
+    id: string;
+    name: string;
+    targetType: TriggerTargetType;
+    sourceType: TriggerSourceType;
+    cronExpression: string | null;
+    eventName: string | null;
+    handlerPath: string | null;
+    callbackUrl: string | null;
+    payload: unknown;
+    status: TriggerStatus;
+    nextRunAt: string | null;
+    lastRunAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ListTriggersResult {
+    triggers: Trigger[];
+}
+interface PublishEventResult {
+    dispatched: number;
+    eventName: string;
+}
+declare class TriggersClient {
+    /** Create a new trigger (cron or event source, task/run/http target) */
+    static create(config: SylphxConfig, options: CreateTriggerOptions): Promise<Trigger>;
+    /** List all triggers for the project */
+    static list(config: SylphxConfig): Promise<ListTriggersResult>;
+    /** Get a trigger by ID */
+    static get(config: SylphxConfig, triggerId: string): Promise<Trigger>;
+    /** Update a trigger */
+    static update(config: SylphxConfig, triggerId: string, options: UpdateTriggerOptions): Promise<Trigger>;
+    /** Delete a trigger */
+    static delete(config: SylphxConfig, triggerId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Pause a trigger */
+    static pause(config: SylphxConfig, triggerId: string): Promise<Trigger>;
+    /** Resume a paused trigger */
+    static resume(config: SylphxConfig, triggerId: string): Promise<Trigger>;
+    /** Fire a trigger immediately (one-shot, regardless of schedule) */
+    static fire(config: SylphxConfig, triggerId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Publish an event — dispatches all active event triggers matching the event name.
+     *
+     * @example
+     * ```typescript
+     * await TriggersClient.publishEvent(config, 'user.signup', { userId: '123', plan: 'pro' })
+     * ```
+     */
+    /**
+     * Publish an event — dispatches all active event triggers matching the event name.
+     * Endpoint: POST /triggers/events
+     *
+     * @example
+     * ```typescript
+     * await TriggersClient.publishEvent(config, 'user.signup', { userId: '123', plan: 'pro' })
+     * ```
+     */
+    static publishEvent(config: SylphxConfig, eventName: string, payload?: Record<string, unknown>): Promise<PublishEventResult>;
+}
+
+export { ACHIEVEMENT_TIER_CONFIG, type AIListModelsOptions, type AIListModelsResponse, type AIMessage, type AIMessageRole, type AIModel, type AIModelInfo, type AIModelsResponse, type AIProvider, type AIRateLimitInfo, type AIRateLimitResponse, type AIRequestType, type AIStreamChunk, type AITool, type AIToolCall, type AIUsageResponse, type AIUsageStats, type AccessTokenPayload, type AchievementCategory, type AchievementCriteria, type AchievementCriterion, type AchievementDefinition, type AchievementTier, type AchievementType, type AchievementUnlockEvent, type AdminUser, AuthenticationError, AuthorizationError, type BalanceResponse, type BatchEvent, type BatchIndexInput, type BatchIndexResult, type Breadcrumb, type BuildLog, type BuildLogHistoryResponse, type CaptureExceptionRequest, type CaptureMessageRequest, type ChatCompletionInput, type ChatCompletionResponse, type ChatInput, type ChatMessage, type ChatResult, type ChatStreamChunk, type CheckoutRequest, type CheckoutResponse, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitState, type CommandResult, type ConsentCategory, type ConsentHistoryEntry, type ConsentHistoryResult, type ConsentPurposeDefaults, type ConsentType, type ContentPart, type CreateOrgInput, type CreatePermissionInput, type CreateRoleInput, type CreateRunOptions, type CreateTriggerOptions, type CriteriaOperator, type CronInput, type CronSchedule, type CronSource, type DatabaseConnectionInfo, type DatabaseStatus, type DatabaseStatusInfo, type DebugCategory, type DeduplicationConfig, type DeleteDocumentInput, type DeployHistoryResponse, type DeployInfo, type DeployStatus, type DynamicRestClient, ERROR_CODE_STATUS, type EmbedInput, type EmbedResult, type EmbeddingInput, type EmbeddingResponse, type LeaderboardEntry as EngagementLeaderboardEntry, type LeaderboardResult as EngagementLeaderboardResult, type EnvVar, type ErrorCode, type ErrorResponse, type EventSource, type ExceptionFrame, type ExceptionValue, type ExecEvent, type ExecOptions, type ExecResult, type FacetsResponse, type FileEvent, type FileInfo, type FileUploadOptions, type FlagContext, type FlagResult, type GetConsentHistoryInput, type GetConsentsInput, type GetFacetsInput, type GetSecretInput, type GetSecretResult, type GetSecretsInput, type GetSecretsResult, type HttpTarget, type IdentifyInput, type IndexDocumentInput, type IndexDocumentResult, InvalidConnectionUrlError, type InviteMemberInput, type InviteUserRequest, type InviteUserResponse, type KvExpireRequest, type KvHgetRequest, type KvHgetallRequest, type KvHsetRequest, type KvIncrRequest, type KvLpushRequest, type KvLrangeRequest, type KvMgetRequest, type KvMsetRequest, type KvRateLimitRequest, type KvRateLimitResult, type KvScanOptions, type KvScanResult, type KvSetOptions, type KvSetRequest, type KvZMember, type KvZaddRequest, type KvZrangeRequest, type LeaderboardAggregation, type LeaderboardDefinition, type LeaderboardEntry$1 as LeaderboardEntry, type LeaderboardOptions, type LeaderboardQueryOptions, type LeaderboardResetPeriod, type LeaderboardResult$1 as LeaderboardResult, type LeaderboardSortDirection, type LinkAnonymousConsentsInput, type ListRunsOptions, type ListRunsResult, type ListScheduledEmailsOptions, type ListSecretKeysInput, type ListTriggersResult, type ListUsersOptions, type ListUsersResult, type LoginHistoryEntry, type LoginRequest, type LoginResponse, type MeResponse, type MemberPermissionsResult, type MonitoringResponse, type MonitoringSeverity, type NativeStepContext, type NativeTaskDefinition, type TaskRunStatus as NativeTaskRunStatus, NetworkError, NotFoundError, type OrgRole, type OrgTokenPayload, type Organization, type OrganizationInvitation, type OrganizationMember, type OrganizationMembership, type PageInput, type PaginatedResponse, type PaginationInput, type ParsedConnectionUrl, type Permission, type Plan, type PortalRequest, type PortalResponse, type ProcessEvent, type ProcessInfo, type ProcessStartOptions, type ProcessSummary, type PublishEventResult, type PushNotification, type PushNotificationPayload, type PushServiceWorkerConfig, type PushSubscription, RETRYABLE_CODES, RateLimitError, type RealtimeEmitRequest, type RealtimeEmitResponse, type RealtimeHistoryRequest, type RealtimeHistoryResponse, type RecordActivityInput, type RecordActivityResult, type RedeemReferralInput, type RedeemResult, type ReferralCode, type ReferralStats, type RegisterInput, type RegisterRequest, type RegisterResponse, type RestClient, type RestClientConfig, type RestDynamicConfig, type paths as RestPaths, type RetryConfig, type RevokeTokenOptions, type Role, type RollbackDeployRequest, type Run, RunHandle, type RunLogsResult, type RunResourceSpec, type RunResult, type RunStatus, type RunTarget, type RunVolumeMount, type CreateRunOptions as RunWorkerOptions, RunsClient, SandboxClient, type SandboxFile, SandboxFiles, type SandboxOptions, SandboxProcesses, type SandboxRecord, SandboxWatch, type ScheduleEmailOptions, type ScheduledEmail, type ScheduledEmailStats, type ScheduledEmailsResult, type SearchInput, type SearchResponse, type SearchResultItem, type SearchStatsResult, type SearchType, type SecretKeyInfo, type SecuritySettings, type SendEmailOptions, type SendResult, type SendTemplatedEmailOptions, type SendToUserOptions, type SessionResult, type SetConsentsInput, type SetEnvVarRequest, type SignedUrlOptions, type SignedUrlResult, StepCompleteSignal, StepSleepSignal, type StreakDefinition, type StreakFrequency, type StreakState, type StreamMessage, type SubmitScoreInput, type SubmitScoreResult, type Subscription, type SuccessResponse, type SylphxClientInput, type SylphxConfig, type SylphxConfigInput, SylphxError, type SylphxErrorCode, type SylphxErrorOptions, type TaskInput, type TaskResult, type TaskStatus, type TaskTarget, type TextCompletionInput, type TextCompletionResponse, TimeoutError, type TokenIntrospectionResult, type TokenResponse, type Tool, type ToolCall, type TrackClickInput, type TrackInput, type Trigger, type TriggerDeployRequest, type TriggerSource, type TriggerSourceType, type TriggerStatus, type TriggerTarget, type TriggerTargetType, TriggersClient, type TwoFactorVerifyRequest, type UpdateOrgInput, type UpdateRoleInput, type UpdateTriggerOptions, type UploadProgressEvent, type UploadResult, type UpsertDocumentInput, type UpsertDocumentResult, type UsageResponse, type User, type UserAchievement, type UserConsent, type UserProfile, ValidationError, type VisionInput, type WatchEntry, type WatchOptions, type WebhookConfig, type WebhookConfigUpdate, type WebhookDeliveriesResult, type WebhookDelivery, type WebhookStats, RunHandle as WorkerHandle, type RunLogsResult as WorkerLogsResult, type RunResourceSpec as WorkerResourceSpec, type RunResult as WorkerResult, type Run as WorkerRun, type RunStatus as WorkerStatus, type RunVolumeMount as WorkerVolumeMount, WorkersClient, acceptAllConsents, acceptOrganizationInvitation, assignMemberRole, batchIndex, canDeleteOrganization, canManageMembers, canManageSettings, cancelScheduledEmail, cancelTask, captureException, captureExceptionRaw, captureMessage, chat, chatStream, checkFlag, complete, createCheckout, createClient, createConfig, createCron, createDynamicRestClient, createOrganization, createPermission, createPortalSession, createRestClient, createRole, createServerClient, createServiceWorkerScript, createStepContext, createTasksHandler, createTracker, debugError, debugLog, debugTimer, debugWarn, declineOptionalConsents, deleteCron, deleteDocument, deleteEnvVar, deleteFile, deleteOrganization, deletePermission, deleteRole, deleteUser, disableDebug, embed, enableDebug, exponentialBackoff, extendedSignUp, forgotPassword, generateAnonymousId, getAchievement, getAchievementPoints, getAchievements, getAllFlags, getAllSecrets, getAllStreaks, getBillingBalance, getBillingUsage, getBuildLogHistory, getCircuitBreakerState, getConsentHistory, getConsentTypes, getDatabaseConnectionString, getDatabaseStatus, getDebugMode, getDeployHistory, getDeployStatus, getErrorCode, getErrorMessage, getFacets, getFileInfo, getFileUrl, getFlagPayload, getFlags, getLeaderboard, getMemberPermissions, getMyReferralCode, getOrganization, getOrganizationInvitations, getOrganizationMembers, getOrganizations, getPlans, getPushPreferences, getRealtimeHistory, getReferralLeaderboard, getReferralStats, getRestErrorMessage, getRole, getScheduledEmail, getScheduledEmailStats, getSearchStats, getSecret, getSecrets, getSession, getSignedUrl, getStreak, getSubscription, getTask, getUser, getUserByEmail, getUserConsents, getUserLeaderboardRank, getVariant, getWebhookConfig, getWebhookDeliveries, getWebhookDelivery, getWebhookStats, hasAllPermissions, hasAnyPermission, hasConsent, hasError, hasPermission, hasRole, hasSecret, identify, incrementAchievementProgress, indexDocument, initPushServiceWorker, installGlobalDebugHelpers, introspectToken, inviteOrganizationMember, inviteUser, isEmailConfigured, isEnabled, isRetryableError, isSylphxError, kvDelete, kvExists, kvExpire, kvGet, kvGetJSON, kvHget, kvHgetall, kvHset, kvIncr, kvLpush, kvLrange, kvMget, kvMset, kvRateLimit, kvScan, kvSet, kvSetJSON, kvZadd, kvZrange, leaveOrganization, linkAnonymousConsents, listEnvVars, listPermissions, listRoles, listScheduledEmails, listSecretKeys, listTasks, listUsers, page, pauseCron, realtimeEmit, recordStreakActivity, recoverStreak, redeemReferralCode, refreshToken, regenerateReferralCode, registerPush, registerPushServiceWorker, removeOrganizationMember, replayWebhookDelivery, rescheduleEmail, resetCircuitBreaker, resetDebugModeCache, resetPassword, resumeCron, revokeAllTokens, revokeOrganizationInvitation, revokeToken, rollbackDeploy, scheduleEmail, scheduleTask, search, sendEmail, sendEmailToUser, sendPush, sendTemplatedEmail, setConsents, setEnvVar, signIn, signOut, signUp, streamToString, submitScore, suspendUser, switchOrg, toSylphxError, track, trackBatch, trackClick, triggerDeploy, unlockAchievement, unregisterPush, updateOrganization, updateOrganizationMemberRole, updatePushPreferences, updateRole, updateUser, updateUserMetadata, updateWebhookConfig, uploadAvatar, uploadFile, upsertDocument, verifyEmail, verifySignature as verifyTaskSignature, verifyTwoFactor, withToken };