@abloatai/ablo 0.9.14 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.10.0
+
+### Minor Changes
+
+- Rename environment enum values to `production` and `sandbox` while preserving the existing `*_live_`/`*_test_` key prefix format.
+
+### Patch Changes
+
+- Stateless HTTP transport for server-side actors, and a canonical environment vocabulary.
+  - **`Ablo({ transport: 'http' })`** returns a stateless `AbloHttpClient` for agents, workers, and serverless — the same `ablo.<model>` surface and coordination plane with no websocket: each call is one HTTP round-trip and identity rides the Bearer credential. The return type narrows so stateful-only APIs (`get`/`getAll`/`onChange`) are compile errors instead of latent runtime gaps.
+  - **Canonical `production` / `sandbox` environments** (new `environment.ts`, exported from the root): `sk_test_` / `sk_live_` remain the wire-level key prefixes but now map to `production` / `sandbox` everywhere — key parsing, source `mode`, and the CLI (which drops the legacy test/live config migration).
+  - **Source-mode commit scoping**: `commit` now forwards `projectId`, `accountScope`, and `environment` to customer storage resolvers, so per-project and sandbox/production traffic can be routed to distinct stores.
+  - **Fixes**: the WebSocket bearer credential is sent in the `ablo.bearer.<token>` subprotocol (never in the URL or proxy logs); `Model` no longer fabricates an `updatedAt` of "now" for records that arrive with only `createdAt`.
+
+## 0.9.15
+
+### Patch Changes
+
+- Package metadata: set the npm description to "The Collaboration Layer For AI Agents" (matching the GitHub repo About) so it stops reverting to the old "State control API…" text on publish.
+
 ## 0.9.14
 
 ### Patch Changes

package/dist/BaseSyncedStore.d.ts

@@ -125,8 +125,9 @@ export interface UserContext {
      *  `kind=agent` and the server applies capability-token auth. */
     kind?: 'user' | 'agent' | 'system';
     /** Restricted (`rk_`) API key for `kind: 'agent'` — the agent's
-     *  bearer credential. Sent as `?authorization=Bearer <token>` on the
-     *  WS upgrade. (Field name predates the Biscuit→opaque-key migration.) */
+     *  bearer credential. Sent in the `ablo.bearer.<token>` WebSocket
+     *  subprotocol, never in the URL. (Field name predates the
+     *  Biscuit→opaque-key migration.) */
     capabilityToken?: string;
     /** Server-authoritative sync groups, supplied by auth/capability
      *  exchange. The SDK does not invent org/user/default groups; app

package/dist/Model.js

@@ -78,11 +78,19 @@ export class Model {
                 ? data.createdAt
                 : new Date(data.createdAt)
             : new Date();
+        // A record that arrives WITH `createdAt` but WITHOUT `updatedAt` is
+        // server/IDB data whose update timestamp didn't survive the wire —
+        // falling back to "now" here fabricated an edit time for every such
+        // record on every bootstrap (the decks gallery sorted everything to
+        // "edited just now"). Fall back to createdAt instead; only a genuinely
+        // new local model (no dates at all) stamps the current time.
         this.updatedAt = data.updatedAt
             ? data.updatedAt instanceof Date
                 ? data.updatedAt
                 : new Date(data.updatedAt)
-            : new Date();
+            : data.createdAt
+                ? new Date(this.createdAt)
+                : new Date();
         this.syncStatus = data.syncStatus || 'pending';
     }
     /**

package/dist/cli.cjs

@@ -279453,13 +279453,12 @@ function asActiveProject(value) {
   return void 0;
 }
 function normalizeStoredMode(value) {
-  if (value === "sandbox" || value === "test") return "sandbox";
-  if (value === "production" || value === "live") return "production";
+  if (value === "sandbox" || value === "production") return value;
   return void 0;
 }
 function extractEntries(obj) {
-  const sandbox = asKeyEntry(obj.sandbox) ?? asKeyEntry(obj.test);
-  const production = asKeyEntry(obj.production) ?? asKeyEntry(obj.live);
+  const sandbox = asKeyEntry(obj.sandbox);
+  const production = asKeyEntry(obj.production);
   if (sandbox || production) {
     return { ...sandbox ? { sandbox } : {}, ...production ? { production } : {} };
   }

package/dist/client/Ablo.d.ts

@@ -29,6 +29,7 @@ import type { IntentStream, IntentWaitOptions, PresenceStream, Snapshot } from '
 import type { ParticipantManager } from '../sync/participants.js';
 import type { ActiveIntent, Duration, Intent, TargetRange } from '../types/streams.js';
 import { type AbloApi, type AbloApiClientOptions, type AbloApiIntents } from './ApiClient.js';
+import { type AbloHttpClient, type AbloHttpClientOptions } from './httpClient.js';
 /**
  * Async function that resolves an apiKey at request time. Use for
  * credential rotation — rotate from a vault, refresh from session
@@ -125,6 +126,19 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * @default 'memory'
      */
     persistence?: AbloPersistence;
+    /**
+     * Transport selector. `'websocket'` (default) is the live client —
+     * persistent socket, local synced pool, `onChange` subscriptions. `'http'`
+     * returns the STATELESS client for server-side actors (agents, workers,
+     * serverless): same `ablo.<model>` surface and coordination plane, but each
+     * call is one HTTP round-trip, identity rides the Bearer credential, and no
+     * socket is ever opened. With `'http'` the return type narrows to
+     * `AbloHttpClient<S>`, so stateful-only capabilities (`get`/`getAll`,
+     * `onChange`) are compile errors rather than latent runtime gaps.
+     *
+     * @default 'websocket'
+     */
+    transport?: 'websocket' | 'http' | undefined;
     /**
      * Bearer auth token. Hosted-cloud consumers pass `apiKey`; self-hosted
      * deployments may pass a bearer token minted by their own auth layer.
@@ -944,7 +958,18 @@ export declare function computeFKDepthPriority(schema: Schema): ReadonlyMap<stri
  * const reports = sync.weatherReports.list({ where: { status: 'pending' } });
  * await sync.weatherReports.create({ location: 'Stockholm', status: 'pending' });
  * ```
+ *
+ * Pass `transport: 'http'` for the stateless server-side client (agents,
+ * workers, serverless) — same `ablo.<model>` surface, no socket:
+ *
+ * ```ts
+ * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
+ * await ablo.tasks.update({ id, data: { status: 'done' } });
+ * ```
  */
+export declare function Ablo<const S extends SchemaRecord>(options: AbloHttpClientOptions<S> & {
+    transport: 'http';
+}): AbloHttpClient<S>;
 export declare function Ablo<const S extends SchemaRecord>(options: AbloOptions<S>): Ablo<S>;
 export declare function Ablo(options: AbloApiClientOptions): AbloApi;
 import type * as _Streams from '../types/streams.js';

package/dist/client/Ablo.js

@@ -37,6 +37,9 @@ import { awaitIntentGrant } from '../sync/awaitIntentGrant.js';
 import { createSnapshot } from '../sync/createSnapshot.js';
 import { createParticipantManager } from '../sync/participants.js';
 import { createProtocolClient, } from './ApiClient.js';
+// Value import is cycle-safe: httpClient.js only value-imports ApiClient.js,
+// which imports this module type-only.
+import { createAbloHttpClient, } from './httpClient.js';
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { shouldUseInMemoryPersistence, } from './persistence.js';
@@ -684,8 +687,13 @@ function resolveCredentialResolver(options) {
 }
 export function Ablo(options) {
     if (options.schema == null) {
+        // The protocol client IS the stateless HTTP plane (string-keyed models),
+        // so `transport: 'http'` needs no special-casing here.
         return createProtocolClient(options);
     }
+    if (options.transport === 'http') {
+        return createAbloHttpClient(options);
+    }
     const internalOptions = options;
     const env = readProcessEnv();
     const authInput = { options, env };

package/dist/environment.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const ENVIRONMENTS: readonly ["production", "sandbox"];
+export type KeyPrefixEnvironment = 'live' | 'test';
+export declare const environmentSchema: z.ZodEnum<{
+    production: "production";
+    sandbox: "sandbox";
+}>;
+export type Environment = z.infer<typeof environmentSchema>;
+export declare function normalizeEnvironment(value: unknown, fallback?: Environment): Environment;
+export declare function environmentFromKeyPrefix(value: KeyPrefixEnvironment): Environment;
+export declare function environmentToKeyPrefix(value: Environment): KeyPrefixEnvironment;
+export declare function isSandboxEnvironment(value: Environment): boolean;

package/dist/environment.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export const ENVIRONMENTS = ['production', 'sandbox'];
+export const environmentSchema = z.enum(ENVIRONMENTS);
+export function normalizeEnvironment(value, fallback = 'production') {
+    const parsed = environmentSchema.safeParse(value);
+    return parsed.success ? parsed.data : fallback;
+}
+export function environmentFromKeyPrefix(value) {
+    return value === 'test' ? 'sandbox' : 'production';
+}
+export function environmentToKeyPrefix(value) {
+    return value === 'sandbox' ? 'test' : 'live';
+}
+export function isSandboxEnvironment(value) {
+    return value === 'sandbox';
+}

package/dist/index.d.ts

@@ -64,6 +64,8 @@ export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionErr
 export type { CommitReceipt, RequiredCapability } from './errors.js';
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errors.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
+export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
+export type { Environment, KeyPrefixEnvironment } from './environment.js';
 export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './client/writeOptionsSchema.js';
 export type { WriteOptionsInput } from './client/writeOptionsSchema.js';
 export type { WriteOptions, MutationOptions } from './interfaces/index.js';

package/dist/index.js

@@ -89,6 +89,7 @@ export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
 // `e.type === 'AbloX'`) plus the HTTP-response translator.
 export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, classifyRecovery, recoveryClassSchema, RECOVERY_CLASSES, } from './errors.js';
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from './auth/credentialSource.js';
+export { ENVIRONMENTS, environmentSchema, normalizeEnvironment, environmentFromKeyPrefix, environmentToKeyPrefix, isSandboxEnvironment, } from './environment.js';
 // THE write-options contract — the one Zod schema for the option bag every
 // write door accepts (`ablo.<model>.create/update/delete`, `commits.create`,
 // the HTTP model routes). The SDK validates against it at each boundary;

package/dist/keys/index.d.ts

@@ -10,16 +10,19 @@
  * client bundle never pulls in `node:crypto`.
  *
  * Format (GitHub-style): `<sk|rk|ek>_<live|test>_<30 base62 body><6-char
- * base62 CRC32 checksum>`. The identifiable prefix + CRC32 checksum let
+ * base62 CRC32 checksum>`. The environment segment is the stable key-prefix
+ * contract; parsed values are immediately mapped to `production` / `sandbox`.
+ * The identifiable prefix + CRC32 checksum let
  * secret scanners detect leaks and let us reject typo'd/forged keys OFFLINE
  * (no DB round-trip). Legacy keys (a ~43-char base64url body, no checksum)
  * still validate by hash — they parse here as `checksummed: false`.
  */
 import { z } from 'zod';
+import { type Environment } from '../environment.js';
 export declare const API_KEY_KINDS: readonly ["secret", "restricted", "ephemeral", "publishable"];
 export type ApiKeyKind = (typeof API_KEY_KINDS)[number];
-export declare const API_KEY_ENVS: readonly ["live", "test"];
-export type ApiKeyEnv = (typeof API_KEY_ENVS)[number];
+export declare const API_KEY_ENVS: readonly ["production", "sandbox"];
+export type ApiKeyEnv = Environment;
 /** A structurally-valid Ablo API key, parsed into its parts. */
 export interface ParsedApiKey {
     /** The original plaintext. */

package/dist/keys/index.js

@@ -10,13 +10,16 @@
  * client bundle never pulls in `node:crypto`.
  *
  * Format (GitHub-style): `<sk|rk|ek>_<live|test>_<30 base62 body><6-char
- * base62 CRC32 checksum>`. The identifiable prefix + CRC32 checksum let
+ * base62 CRC32 checksum>`. The environment segment is the stable key-prefix
+ * contract; parsed values are immediately mapped to `production` / `sandbox`.
+ * The identifiable prefix + CRC32 checksum let
  * secret scanners detect leaks and let us reject typo'd/forged keys OFFLINE
  * (no DB round-trip). Legacy keys (a ~43-char base64url body, no checksum)
  * still validate by hash — they parse here as `checksummed: false`.
  */
 import { createHash, randomBytes } from 'node:crypto';
 import { z } from 'zod';
+import { ENVIRONMENTS, environmentFromKeyPrefix, environmentToKeyPrefix, } from '../environment.js';
 // ── Vocabulary ──────────────────────────────────────────────────────────
 // The Stripe-style key model:
 //   secret (sk_)      — backend / server-to-server / agents. Full authority. Never in a browser.
@@ -29,7 +32,7 @@ import { z } from 'zod';
 //                       it; it grants read access to the org's data plane and cannot write
 //                       or reach any control-plane operation.
 export const API_KEY_KINDS = ['secret', 'restricted', 'ephemeral', 'publishable'];
-export const API_KEY_ENVS = ['live', 'test'];
+export const API_KEY_ENVS = ENVIRONMENTS;
 const PREFIX_BY_KIND = {
     secret: 'sk',
     restricted: 'rk',
@@ -115,7 +118,13 @@ export const apiKeySchema = z.string().transform((raw, ctx) => {
         ctx.addIssue({ code: 'custom', message: 'API key checksum mismatch' });
         return z.NEVER;
     }
-    return { raw, kind: KIND_BY_PREFIX[prefix], env: env, body, checksummed };
+    return {
+        raw,
+        kind: KIND_BY_PREFIX[prefix],
+        env: environmentFromKeyPrefix(env),
+        body,
+        checksummed,
+    };
 });
 // ── Derived validators (thin wrappers over the same spec) ───────────────
 /** Parse + fully validate (incl. checksum). Returns null when invalid. */
@@ -140,9 +149,9 @@ export function keyChecksumMatches(raw) {
  * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
  * once), its SHA-256 hash (persisted), and the 12-char display prefix.
  */
-export function generateApiKey(env = 'live', kind = 'secret') {
+export function generateApiKey(env = 'production', kind = 'secret') {
     const body = randomBase62(KEY_BODY_LEN);
-    const payload = `${PREFIX_BY_KIND[kind]}_${env}_${body}`;
+    const payload = `${PREFIX_BY_KIND[kind]}_${environmentToKeyPrefix(env)}_${body}`;
     const plaintext = `${payload}${checksum6(payload)}`;
     return { plaintext, hash: hashApiKey(plaintext), prefix: plaintext.slice(0, 12) };
 }

package/dist/schema/diff.d.ts

@@ -124,7 +124,7 @@ export type WarningCode = 'drop_model' | 'drop_field' | 'risky_cast' | 'lossy_re
 /** A model disappears from what this plane's READERS resolve, without any
  *  table being dropped. Emitted by the server's push gate (not
  *  `classifyMigration`) when a first sandbox push shadows the production
- *  artifact that sandbox readers were served via the registry's test→live
+ *  artifact that sandbox readers were served via the registry's sandbox→production
  *  fallback. The data plane is untouched — the loss is visibility. */
  | 'remove_model';
 export type BlockerCode = 'required_field_added' | 'made_required';

package/dist/server/commit.d.ts

@@ -15,6 +15,7 @@
  */
 import type { ParticipantKind, ConfirmationState } from '../schema/sync-delta-row.js';
 import type { ParticipantRef } from '../schema/sync-delta-wire.js';
+import type { Environment } from '../environment.js';
 export interface CommitContext {
     participantId: string;
     /**
@@ -24,6 +25,19 @@ export interface CommitContext {
      */
     participantKind: ParticipantKind;
     organizationId: string;
+    /**
+     * Product/project scope for routing source-mode storage. Omitted means the
+     * org-default project (the legacy behavior).
+     */
+    projectId?: string;
+    /** Optional external account scope forwarded to storage resolvers. */
+    accountScope?: string;
+    /**
+     * Canonical environment for this commit. Source-mode adapters forward this to
+     * customer handlers so sandbox and production traffic can hit distinct
+     * customer-owned stores.
+     */
+    environment?: Environment;
     /**
      * The participant's own subscribed sync groups (from the WS upgrade or
      * capability token). Appended to every delta's `sync_groups` so writes fan

package/dist/source/index.d.ts

@@ -1,4 +1,5 @@
 import type { Schema, SchemaRecord, InferCreate } from '../schema/schema.js';
+import type { Environment } from '../environment.js';
 import type { DataSourceAdapter } from './adapter.js';
 export type SourcePrimitive = string | number | boolean | null;
 export type SourceWhere = readonly [field: string, value: SourcePrimitive] | readonly [
@@ -47,21 +48,21 @@ export interface SourceRequestContext {
     readonly organizationId?: string;
     readonly requiredSyncGroups?: readonly string[];
     /**
-     * Test/live mode for this request. Customers branch their source
-     * handlers on this (`if (mode === 'test') db = testDb`) so test
+     * Production/sandbox mode for this request. Customers branch their source
+     * handlers on this (`if (mode === 'sandbox') db = sandboxDb`) so sandbox
      * traffic exercises the same code path against an isolated store.
      *
-     * Mirrors Stripe's `sk_test_` / `sk_live_` distinction: same wire
+     * Mirrors Stripe's `sk_test_` / `sk_live_` prefixes: same wire
      * shape, same handler code, different namespace. Ablo's server-side
      * fan-out does not yet partition deltas by mode — that lands when
      * `sync_deltas.mode` ships. Until then, isolation is enforced
      * customer-side via this field, which is the right boundary anyway
      * (the customer's database is where the canonical data lives).
      *
-     * Defaults to `'live'` when omitted so callers that don't opt in
+     * Defaults to `'production'` when omitted so callers that don't opt in
      * keep the existing behavior.
      */
-    readonly mode?: 'test' | 'live';
+    readonly mode?: Environment;
 }
 export interface SourceOperation {
     readonly type: 'CREATE' | 'UPDATE' | 'DELETE' | 'ARCHIVE' | 'UNARCHIVE';

package/dist/sync/SyncWebSocket.d.ts

@@ -92,11 +92,10 @@ export interface SyncWebSocketOptions {
     kind?: 'user' | 'agent' | 'system';
     /**
      * The agent's bearer credential — a restricted (`rk_`) API key. When
-     * set, sent as `?authorization=Bearer+<token>` on the WS upgrade —
-     * query-param form so it works in both Node (no header support) and
-     * browsers. The server's auth path accepts either form. Required for
-     * `kind: 'agent'`; ignored for `kind: 'user'`. (Field name predates
-     * the Biscuit→opaque-key migration.)
+     * set, sent in the `ablo.bearer.<token>` WebSocket subprotocol so the
+     * credential stays out of URLs and proxy logs. Required for `kind: 'agent'`;
+     * ignored for `kind: 'user'`. (Field name predates the Biscuit→opaque-key
+     * migration.)
      */
     capabilityToken?: string;
     /**

package/dist/transactions/TransactionQueue.js

@@ -949,6 +949,12 @@ export class TransactionQueue extends EventEmitter {
                     // Ensure derived fields exist (covers restored/persisted transactions)
                     this.ensureDerivedFields(a);
                     this.ensureDerivedFields(b);
+                    if (a.modelName === b.modelName && a.modelId === b.modelId && a.type !== b.type) {
+                        if (a.type === 'create')
+                            return -1;
+                        if (b.type === 'create')
+                            return 1;
+                    }
                     return a.priorityScore - b.priorityScore;
                 });
                 // Get batch (now guaranteed to have parent entities before children)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.9.14",
-  "description": "State control API for AI agents and collaborative apps.",
+  "version": "0.10.0",
+  "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {
@@ -83,6 +83,11 @@
       "import": "./dist/keys/index.js",
       "default": "./dist/keys/index.js"
     },
+    "./environment": {
+      "types": "./dist/environment.d.ts",
+      "import": "./dist/environment.js",
+      "default": "./dist/environment.js"
+    },
     "./wire": {
       "types": "./dist/wire/index.d.ts",
       "import": "./dist/wire/index.js",