@hybridb/sdk 0.1.0

package/README.md

@@ -0,0 +1,220 @@
+# @hybridb/sdk
+
+**Official TypeScript SDK for the [Stellrai](https://stellrai.com) governed execution runtime.**
+
+> Stellrai doesn't care how you built your app. It governs how it executes.
+
+Build with any framework, any database, any stack. Route governed actions through `@hybridb/sdk` — and every critical operation becomes decided, audited, and reversible by default.
+
+---
+
+## What this SDK does
+
+When your app needs to perform a **governed action** — an AI decision, a payment, identity resolution, an external provider call, or any audit-required state change — you route it through this SDK. Everything else in your app stays exactly as it was.
+
+| Governed (use SDK) | Not governed (use any tool) |
+|---|---|
+| AI decisions and inferences | UI rendering |
+| Payments and financial operations | Local database reads/writes |
+| Identity resolution and auth | In-memory computation |
+| External provider calls (Stripe, KYC, etc.) | Draft content and UI state |
+| Audit-required state changes | Application configuration |
+
+---
+
+## Installation
+
+```bash
+npm install @hybridb/sdk
+# or
+pnpm add @hybridb/sdk
+# or
+yarn add @hybridb/sdk
+```
+
+---
+
+## Quick start
+
+### 1. Get an API key
+
+Sign up at [stellrai.com](https://stellrai.com) — free tier, no credit card required. Your API key is shown once at registration.
+
+### 2. Initialise the client
+
+```typescript
+import { HybriDBClient } from '@hybridb/sdk';
+
+const hdb = new HybriDBClient({
+  baseUrl: 'https://hybridb.stellrai.com',
+  apiKey:  process.env.HYBRIDB_API_KEY!,
+});
+```
+
+### 3. Trigger a governed pipeline
+
+```typescript
+const execution = await hdb.triggerPipeline({
+  pipelineId:     'process-payment',
+  input:          { userId: 'u_123', amount: 15000, currency: 'USD' },
+  idempotencyKey: crypto.randomUUID(),
+});
+
+console.log(execution.id);     // exec_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+console.log(execution.status); // 'completed'
+```
+
+### 4. Rollback a failed execution
+
+```typescript
+if (execution.status === 'failed') {
+  const result = await hdb.reversibility.rollback(execution.id, {
+    rollbackType: 'full',
+    reason:       'Payment processor returned 422',
+  });
+
+  console.log(result.outcome);         // 'success'
+  console.log(result.stepsRolledBack); // ['charge', 'reserve', 'notify']
+  console.log(result.durationMs);      // 2840
+}
+```
+
+### 5. Replay from a checkpoint
+
+```typescript
+const checkpoints = await hdb.reversibility.getCheckpoints(execution.id);
+
+const replay = await hdb.reversibility.replay(execution.id, {
+  fromCheckpoint: checkpoints[1].id,  // resume after step 2 — not from step zero
+  reason:         'Retry notification step after rate limit',
+});
+
+console.log(replay.newExecutionId);    // new child execution
+console.log(replay.parentExecutionId); // original execution
+```
+
+---
+
+## API reference
+
+### `HybriDBClient`
+
+```typescript
+const hdb = new HybriDBClient({
+  baseUrl:     string,   // required — e.g. 'https://hybridb.stellrai.com'
+  apiKey:      string,   // required — your Stellrai API key
+  timeout?:    number,   // ms, default 10000
+  retries?:    number,   // default 3
+  retryDelay?: number,   // ms, default 500
+});
+```
+
+### Pipelines
+
+```typescript
+hdb.triggerPipeline(input)           // trigger a governed pipeline
+hdb.getPipelineExecution(executionId) // get execution status
+```
+
+### Reversibility
+
+```typescript
+hdb.reversibility.rollback(executionId, input)          // rollback full / selective / to checkpoint
+hdb.reversibility.replay(executionId, input)            // replay from a specific checkpoint
+hdb.reversibility.getCheckpoints(executionId)           // list all checkpoints
+hdb.reversibility.getCheckpoint(executionId, id)        // get checkpoint (checksum-verified)
+hdb.reversibility.getRollbackLog(executionId)           // audit log of rollback operations
+hdb.reversibility.getCircuitBreaker(pipelineId)         // get circuit breaker status
+hdb.reversibility.setCircuitBreaker(pipelineId, input)  // open / close circuit breaker
+```
+
+### Decisions
+
+```typescript
+hdb.requestDecision(request) // policy-governed decision
+hdb.getDecision(decisionId)  // retrieve a past decision
+```
+
+### Identity & Auth
+
+```typescript
+hdb.authenticate(input)         // email + password → token pair
+hdb.refreshToken(refreshToken)  // refresh an access token
+hdb.revokeSession()             // invalidate current session
+hdb.verifyToken(token)          // local JWT verification via JWKS (requires jose)
+hdb.actors.createApiKey(actorId, input)
+hdb.actors.revokeApiKey(actorId, keyId)
+hdb.actors.createMapping(actorId, input)
+hdb.orgs.addMember(orgId, input)
+hdb.orgs.updateMemberRole(orgId, actorId, role)
+hdb.orgs.revokeMember(orgId, actorId)
+hdb.orgs.listMembers(orgId)
+```
+
+### Events & Audit
+
+```typescript
+hdb.publishEvent(input)          // publish a business event
+hdb.queryAuditLog(params)        // query the immutable audit log
+hdb.health()                     // check API status
+```
+
+### React context (optional)
+
+```typescript
+import { HybriDBProvider, useHybriDBClient } from '@hybridb/sdk/react';
+
+// Wrap at app root
+<HybriDBProvider client={hdb}>
+  {children}
+</HybriDBProvider>
+
+// Use in any component
+const { client } = useHybriDBClient();
+```
+
+---
+
+## Error handling
+
+All SDK methods throw `HybriDBError` on failure. Never swallow these — they represent governance failures, not application errors.
+
+```typescript
+import { HybriDBClient, HybriDBError } from '@hybridb/sdk';
+
+try {
+  const execution = await hdb.triggerPipeline({ ... });
+} catch (err) {
+  if (err instanceof HybriDBError) {
+    console.error(err.code);    // e.g. 'POLICY_BLOCKED', 'RATE_LIMITED'
+    console.error(err.message); // human-readable description
+    console.error(err.details); // structured detail object (when present)
+  }
+  throw err; // let errors propagate — don't hide governance failures
+}
+```
+
+---
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5+ (optional but recommended)
+- `jose` ^5.0 (only required if you use `hdb.verifyToken()` — auto-installed as dependency)
+- React 18+ (only required for `@hybridb/sdk/react` — optional peer dependency)
+
+---
+
+## Links
+
+- **Dashboard:** [stellrai.com/dashboard](https://stellrai.com/dashboard)
+- **API Reference:** [hybridb.stellrai.com/docs](https://hybridb.stellrai.com/docs)
+- **OpenAPI spec:** [hybridb.stellrai.com/openapi.json](https://hybridb.stellrai.com/openapi.json)
+- **Status:** [hybridb.stellrai.com/health](https://hybridb.stellrai.com/health)
+- **Issues:** [github.com/3pplea-Holdings/stellrai/issues](https://github.com/3pplea-Holdings/stellrai/issues)
+
+---
+
+## License
+
+MIT © [3PPLEA Holdings LLC](https://stellrai.com)

package/dist/client-DzNX2jDR.d.cts

@@ -0,0 +1,157 @@
+import { TokenPair, ActorContext, UUID, IdentityMapping, OrgMembership, InitiateRollbackInput, RollbackResult, InitiateReplayInput, ReplayResult, CheckpointSummary, Checkpoint, RollbackLog, CircuitBreakerStatus, SetCircuitBreakerInput, DecisionInput, DecisionResponse, TriggerPipelineInput, PipelineExecution, PublishEventInput, HybriDBEvent, PaginatedResponse, AuditEntry } from './common/index.js';
+
+interface HybriDBClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+}
+interface AuthenticateInput {
+    email: string;
+    password: string;
+    orgId?: string;
+}
+interface CreateMappingInput {
+    providerId: string;
+    externalId: string;
+    userId: string;
+    actorId: string;
+}
+interface OrgMemberInput {
+    actorId: string;
+    role: string;
+}
+interface ApiKeyInput {
+    name?: string;
+    scopes: string[];
+    expiresAt?: string;
+}
+interface AuditQueryParams {
+    actorId?: string;
+    action?: string;
+    outcome?: string;
+    decisionId?: string;
+    sessionId?: string;
+    from?: string;
+    to?: string;
+    page?: number;
+    limit?: number;
+}
+declare class HybriDBClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly retries;
+    private readonly retryDelay;
+    constructor(config: HybriDBClientConfig);
+    /** Exchange email + password for an access + refresh token pair. */
+    authenticate(input: AuthenticateInput): Promise<TokenPair>;
+    /** Refresh an access token using a refresh token. */
+    refreshToken(refreshToken: string): Promise<TokenPair>;
+    /** Revoke the current session (requires authenticated API key/JWT). */
+    revokeSession(): Promise<void>;
+    /**
+     * Verify a JWT token locally using JWKS from the hybriDB server.
+     * Returns the decoded actor context without making a decision API call.
+     * JWKS is cached for 1 hour (spec: Cache-Control: max-age=3600).
+     */
+    verifyToken(token: string): Promise<ActorContext>;
+    /** Fetch JWKS from the hybriDB server (cached for 1 hour). */
+    getJwks(): Promise<{
+        keys: Record<string, unknown>[];
+    }>;
+    /** Namespace for actor management operations. */
+    readonly actors: {
+        /** Issue an API key for an actor. Requires actor:admin scope. */
+        readonly createApiKey: (actorId: UUID, input: ApiKeyInput) => Promise<{
+            id: string;
+            key: string;
+        }>;
+        /** Revoke an API key. Requires actor:admin scope. */
+        readonly revokeApiKey: (actorId: UUID, keyId: UUID) => Promise<void>;
+        /** Create an identity mapping (external provider → actor). Requires actor:write scope. */
+        readonly createMapping: (actorId: UUID, input: CreateMappingInput) => Promise<IdentityMapping>;
+    };
+    /** Namespace for organisation membership operations. */
+    readonly orgs: {
+        /** Add a member to an organisation. Requires org:admin scope. */
+        readonly addMember: (orgId: UUID, input: OrgMemberInput) => Promise<OrgMembership>;
+        /** Update a member's role. Requires org:admin scope. */
+        readonly updateMemberRole: (orgId: UUID, actorId: UUID, role: string) => Promise<OrgMembership>;
+        /** Revoke an actor's membership. Requires org:admin scope. */
+        readonly revokeMember: (orgId: UUID, actorId: UUID) => Promise<void>;
+        /** List organisation members. Requires org:read scope. */
+        readonly listMembers: (orgId: UUID) => Promise<OrgMembership[]>;
+    };
+    /** Namespace for Reversible Autonomy operations (v2.4). */
+    readonly reversibility: {
+        /**
+         * Initiate a rollback for an execution.
+         * Types: 'full' (all steps), 'selective' (targetSteps list), 'to_checkpoint'.
+         * Requires pipeline:rollback scope.
+         */
+        readonly rollback: (executionId: UUID, input: Omit<InitiateRollbackInput, "executionId">) => Promise<RollbackResult>;
+        /**
+         * Initiate a replay from a checkpoint.
+         * Creates a new child execution starting from the checkpoint's step.
+         * Requires pipeline:replay scope.
+         */
+        readonly replay: (executionId: UUID, input: Omit<InitiateReplayInput, "executionId">) => Promise<ReplayResult>;
+        /**
+         * List all checkpoints for an execution (ordered by step_index asc).
+         * Requires pipeline:read scope.
+         */
+        readonly getCheckpoints: (executionId: UUID) => Promise<CheckpointSummary[]>;
+        /**
+         * Get a specific checkpoint (with checksum verification).
+         * Throws REPLAY_CONTEXT_INVALID if checksum mismatches.
+         * Requires pipeline:read scope.
+         */
+        readonly getCheckpoint: (executionId: UUID, checkpointId: UUID) => Promise<Checkpoint>;
+        /**
+         * List all rollback log entries for an execution.
+         * Requires pipeline:read scope.
+         */
+        readonly getRollbackLog: (executionId: UUID) => Promise<RollbackLog[]>;
+        /**
+         * Get circuit breaker status for a pipeline.
+         * Requires pipeline:read scope.
+         */
+        readonly getCircuitBreaker: (pipelineId: UUID) => Promise<CircuitBreakerStatus>;
+        /**
+         * Open or close the circuit breaker for a pipeline.
+         * Opening halts all future executions immediately.
+         * Requires pipeline:circuit_breaker scope.
+         */
+        readonly setCircuitBreaker: (pipelineId: UUID, input: Omit<SetCircuitBreakerInput, "pipelineId">) => Promise<CircuitBreakerStatus>;
+    };
+    requestDecision(request: DecisionInput): Promise<DecisionResponse>;
+    getDecision(decisionId: UUID): Promise<DecisionResponse>;
+    triggerPipeline(input: TriggerPipelineInput): Promise<PipelineExecution>;
+    getPipelineExecution(executionId: UUID): Promise<PipelineExecution>;
+    /** Publish a business event. Note: use actorId (v1.2), not identityId. */
+    publishEvent(input: PublishEventInput): Promise<HybriDBEvent>;
+    queryAuditLog(params: AuditQueryParams): Promise<PaginatedResponse<AuditEntry>>;
+    health(): Promise<{
+        status: string;
+        version: string;
+    }>;
+    private get;
+    private getPublic;
+    private post;
+    private postPublic;
+    private patch;
+    private delete;
+    private request;
+    private unwrap;
+    private isRetryable;
+    private sleep;
+}
+declare class HybriDBError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, details?: Record<string, unknown> | undefined);
+}
+
+export { type ApiKeyInput as A, type CreateMappingInput as C, HybriDBClient as H, type OrgMemberInput as O, type AuditQueryParams as a, type AuthenticateInput as b, type HybriDBClientConfig as c, HybriDBError as d };

package/dist/client-DzNX2jDR.d.ts

@@ -0,0 +1,157 @@
+import { TokenPair, ActorContext, UUID, IdentityMapping, OrgMembership, InitiateRollbackInput, RollbackResult, InitiateReplayInput, ReplayResult, CheckpointSummary, Checkpoint, RollbackLog, CircuitBreakerStatus, SetCircuitBreakerInput, DecisionInput, DecisionResponse, TriggerPipelineInput, PipelineExecution, PublishEventInput, HybriDBEvent, PaginatedResponse, AuditEntry } from './common/index.js';
+
+interface HybriDBClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+}
+interface AuthenticateInput {
+    email: string;
+    password: string;
+    orgId?: string;
+}
+interface CreateMappingInput {
+    providerId: string;
+    externalId: string;
+    userId: string;
+    actorId: string;
+}
+interface OrgMemberInput {
+    actorId: string;
+    role: string;
+}
+interface ApiKeyInput {
+    name?: string;
+    scopes: string[];
+    expiresAt?: string;
+}
+interface AuditQueryParams {
+    actorId?: string;
+    action?: string;
+    outcome?: string;
+    decisionId?: string;
+    sessionId?: string;
+    from?: string;
+    to?: string;
+    page?: number;
+    limit?: number;
+}
+declare class HybriDBClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly retries;
+    private readonly retryDelay;
+    constructor(config: HybriDBClientConfig);
+    /** Exchange email + password for an access + refresh token pair. */
+    authenticate(input: AuthenticateInput): Promise<TokenPair>;
+    /** Refresh an access token using a refresh token. */
+    refreshToken(refreshToken: string): Promise<TokenPair>;
+    /** Revoke the current session (requires authenticated API key/JWT). */
+    revokeSession(): Promise<void>;
+    /**
+     * Verify a JWT token locally using JWKS from the hybriDB server.
+     * Returns the decoded actor context without making a decision API call.
+     * JWKS is cached for 1 hour (spec: Cache-Control: max-age=3600).
+     */
+    verifyToken(token: string): Promise<ActorContext>;
+    /** Fetch JWKS from the hybriDB server (cached for 1 hour). */
+    getJwks(): Promise<{
+        keys: Record<string, unknown>[];
+    }>;
+    /** Namespace for actor management operations. */
+    readonly actors: {
+        /** Issue an API key for an actor. Requires actor:admin scope. */
+        readonly createApiKey: (actorId: UUID, input: ApiKeyInput) => Promise<{
+            id: string;
+            key: string;
+        }>;
+        /** Revoke an API key. Requires actor:admin scope. */
+        readonly revokeApiKey: (actorId: UUID, keyId: UUID) => Promise<void>;
+        /** Create an identity mapping (external provider → actor). Requires actor:write scope. */
+        readonly createMapping: (actorId: UUID, input: CreateMappingInput) => Promise<IdentityMapping>;
+    };
+    /** Namespace for organisation membership operations. */
+    readonly orgs: {
+        /** Add a member to an organisation. Requires org:admin scope. */
+        readonly addMember: (orgId: UUID, input: OrgMemberInput) => Promise<OrgMembership>;
+        /** Update a member's role. Requires org:admin scope. */
+        readonly updateMemberRole: (orgId: UUID, actorId: UUID, role: string) => Promise<OrgMembership>;
+        /** Revoke an actor's membership. Requires org:admin scope. */
+        readonly revokeMember: (orgId: UUID, actorId: UUID) => Promise<void>;
+        /** List organisation members. Requires org:read scope. */
+        readonly listMembers: (orgId: UUID) => Promise<OrgMembership[]>;
+    };
+    /** Namespace for Reversible Autonomy operations (v2.4). */
+    readonly reversibility: {
+        /**
+         * Initiate a rollback for an execution.
+         * Types: 'full' (all steps), 'selective' (targetSteps list), 'to_checkpoint'.
+         * Requires pipeline:rollback scope.
+         */
+        readonly rollback: (executionId: UUID, input: Omit<InitiateRollbackInput, "executionId">) => Promise<RollbackResult>;
+        /**
+         * Initiate a replay from a checkpoint.
+         * Creates a new child execution starting from the checkpoint's step.
+         * Requires pipeline:replay scope.
+         */
+        readonly replay: (executionId: UUID, input: Omit<InitiateReplayInput, "executionId">) => Promise<ReplayResult>;
+        /**
+         * List all checkpoints for an execution (ordered by step_index asc).
+         * Requires pipeline:read scope.
+         */
+        readonly getCheckpoints: (executionId: UUID) => Promise<CheckpointSummary[]>;
+        /**
+         * Get a specific checkpoint (with checksum verification).
+         * Throws REPLAY_CONTEXT_INVALID if checksum mismatches.
+         * Requires pipeline:read scope.
+         */
+        readonly getCheckpoint: (executionId: UUID, checkpointId: UUID) => Promise<Checkpoint>;
+        /**
+         * List all rollback log entries for an execution.
+         * Requires pipeline:read scope.
+         */
+        readonly getRollbackLog: (executionId: UUID) => Promise<RollbackLog[]>;
+        /**
+         * Get circuit breaker status for a pipeline.
+         * Requires pipeline:read scope.
+         */
+        readonly getCircuitBreaker: (pipelineId: UUID) => Promise<CircuitBreakerStatus>;
+        /**
+         * Open or close the circuit breaker for a pipeline.
+         * Opening halts all future executions immediately.
+         * Requires pipeline:circuit_breaker scope.
+         */
+        readonly setCircuitBreaker: (pipelineId: UUID, input: Omit<SetCircuitBreakerInput, "pipelineId">) => Promise<CircuitBreakerStatus>;
+    };
+    requestDecision(request: DecisionInput): Promise<DecisionResponse>;
+    getDecision(decisionId: UUID): Promise<DecisionResponse>;
+    triggerPipeline(input: TriggerPipelineInput): Promise<PipelineExecution>;
+    getPipelineExecution(executionId: UUID): Promise<PipelineExecution>;
+    /** Publish a business event. Note: use actorId (v1.2), not identityId. */
+    publishEvent(input: PublishEventInput): Promise<HybriDBEvent>;
+    queryAuditLog(params: AuditQueryParams): Promise<PaginatedResponse<AuditEntry>>;
+    health(): Promise<{
+        status: string;
+        version: string;
+    }>;
+    private get;
+    private getPublic;
+    private post;
+    private postPublic;
+    private patch;
+    private delete;
+    private request;
+    private unwrap;
+    private isRetryable;
+    private sleep;
+}
+declare class HybriDBError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, details?: Record<string, unknown> | undefined);
+}
+
+export { type ApiKeyInput as A, type CreateMappingInput as C, HybriDBClient as H, type OrgMemberInput as O, type AuditQueryParams as a, type AuthenticateInput as b, type HybriDBClientConfig as c, HybriDBError as d };