@abloatai/ablo 0.9.15 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.10.1
+
+### Patch Changes
+
+- Docs: add the 0.10.0 entry to the Version History & Migration Guide — the `test`/`live` → `sandbox`/`production` environment enum rename (key prefixes unchanged) and the new `transport: 'http'` stateless client.
+
+## 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/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/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/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/docs/migration.md

@@ -11,6 +11,7 @@ change when you upgrade.
 
 | Version | What changed | What to do |
 |---|---|---|
+| **0.10.0** | Environment enum renamed `test`/`live` → `sandbox`/`production` | Update code that branches on the environment (e.g. source `mode`): `'test'`→`'sandbox'`, `'live'`→`'production'`. Key prefixes `sk_test_`/`sk_live_` are unchanged |
 | **0.9.2** | `turn` primitive + agent-work `tasks` resource removed | Coordinate with `claim`; mint a scoped session instead of `agent().run()` |
 | **0.9.2** | `intents` deprecated in favor of `claim` | Use `ablo.<model>.claim`; `ablo.intents` is now `@internal` |
 | **0.9.0** | One options object per verb | `update(id, data, opts)` → `update({ id, data, ...opts })` |
@@ -23,6 +24,57 @@ change when you upgrade.
 
 ---
 
+## 0.10.0 — environment enum `sandbox` / `production`; stateless HTTP transport
+
+### Environment enum rename (the only breaking change)
+
+The canonical environment values are now **`production`** and **`sandbox`** (was
+`live` and `test`). This is a *vocabulary* change at the type/API layer — the
+on-the-wire key prefixes are **unchanged**: keys are still `sk_test_…` /
+`sk_live_…` and parse exactly as before. What changed is the enum you see in
+code: `Environment`, the source-handler `mode` field, and `ApiKeyEnv` now read
+`production` / `sandbox`.
+
+You only need to act if your code branches on the environment value — most
+commonly a Data Source handler keyed on `mode`. The mapping is exactly
+`test → sandbox`, `live → production`:
+
+```diff
+  const handler = createSourceHandler({
+    read: async ({ mode }) => {
+-     const db = mode === 'test' ? testDb : liveDb;
++     const db = mode === 'sandbox' ? sandboxDb : productionDb;
+      // …
+    },
+  });
+```
+
+`commit` now also forwards `projectId`, `accountScope`, and `environment` to
+source resolvers, so per-project and per-environment traffic can be routed to
+distinct stores.
+
+> **CLI note:** the legacy single-file config that stored `test`/`live` key
+> buckets is no longer auto-migrated. If `ablo status` can't find your keys after
+> upgrading, re-run `ablo login` to write the current `sandbox`/`production`
+> layout.
+
+### New (non-breaking): `transport: 'http'`
+
+`Ablo({ transport: 'http' })` returns a stateless `AbloHttpClient` for
+server-side actors (agents, workers, serverless): the same `ablo.<model>` surface
+and `claim` coordination, but each call is one HTTP round-trip with identity on
+the Bearer credential — no websocket, no local synced pool. The return type
+narrows, so stateful-only APIs (`get` / `getAll` / `onChange`) become compile
+errors instead of latent runtime gaps. Existing code keeps the default
+`'websocket'` transport, unchanged.
+
+```ts
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
+await ablo.tasks.update({ id, data: { status: 'done' } });
+```
+
+---
+
 ## 0.9.2 — `turn` / agent-`tasks` removed; `intents` deprecated
 
 The SDK's coordination surface is now exactly two things: `ablo.<model>` writes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.9.15",
+  "version": "0.10.1",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",