@abloatai/ablo 0.5.0 → 0.6.0

package/dist/react/useQuery.d.ts

@@ -1,123 +0,0 @@
-import type { ModelScope } from '../types/index.js';
-import type { Schema } from '../schema/schema.js';
-import type { InferModel } from '../schema/schema.js';
-import type { ResolveSchema } from '../types/global.js';
-/** Narrow model-key union for the zero-arg overload. */
-type GlobalModelKey = ResolveSchema extends {
-    models: infer M;
-} ? keyof M & string : string;
-/** Typed entity shape for a given model key. Falls back to a loose shape
- * when the resolved schema doesn't extend the full `Schema` contract
- * (i.e., no global augmentation present). */
-type GlobalEntity<K extends string> = ResolveSchema extends Schema ? K extends keyof ResolveSchema['models'] ? InferModel<ResolveSchema, K> : Record<string, unknown> : Record<string, unknown>;
-/**
- * Compatibility query hook for entity collections.
- *
- * Prefer selector reads for new integrations:
- *
- * ```ts
- * const tasks = useAblo((ablo) =>
- *   ablo.tasks.list({ where: { status: 'todo' } }),
- * );
- * ```
- *
- * This hook remains for older string-keyed integrations.
- *
- * **Typed overload:**
- * ```ts
- * import { schema } from '@/sync/schema';
- * const chats = useQuery(schema, 'chats', { where: { userId } });
- * // chats is fully typed: Chat[] with displayTitle, icon, color, etc.
- * ```
- *
- * **Untyped overload (legacy):**
- * ```ts
- * const chats = useQuery('Chat');
- * // chats is Record<string, unknown>[]
- * ```
- */
-export interface QueryOptions<T = Record<string, unknown>> {
-    /** Declarative field-level filter. Shallow match: all specified fields must match. */
-    where?: Partial<T>;
-    /** Arbitrary predicate function for complex logic. Applied AFTER where. */
-    filter?: (entity: T) => boolean;
-    /** Sort field name. */
-    orderBy?: keyof T & string;
-    /** Sort direction. Default: 'asc'. */
-    order?: 'asc' | 'desc';
-    /** Max results. */
-    limit?: number;
-    /** Skip N results (pagination). */
-    offset?: number;
-    /** Filter by model scope (live, archived, all). Default: live. */
-    scope?: ModelScope;
-}
-/**
- * Typed query (explicit schema arg).
- *
- * @deprecated Prefer `useAblo((ablo) => ablo.<model>.list(options))` for new
- * integrations. This overload remains for compatibility with older
- * string-keyed React code.
- *
- * ```ts
- * const tasks = useQuery(schema, 'tasks', { where: { status: 'todo' } });
- * // tasks: Task[] — fully typed from Zod shape + computed getters
- * ```
- */
-export declare function useQuery<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K, options?: QueryOptions<InferModel<S, K>>): InferModel<S, K>[];
-/**
- * Typed query (global-augmented): pass just the model key. Resolves
- * the schema from the `AbloSync` global augmentation the consumer
- * declared in a `.d.ts`. No `schema` arg at the call site — this is
- * the Liveblocks-style ergonomic path.
- *
- * @deprecated Prefer `useAblo((ablo) => ablo.<model>.list(options))` for new
- * integrations. This overload remains for compatibility with older
- * string-keyed React code.
- *
- * ```ts
- * // apps/your-app/src/ablo-sync.d.ts
- * declare global { interface AbloSync { Schema: typeof schema } }
- *
- * // any component
- * const tasks = useQuery('tasks', { where: { status: 'todo' } });
- * // tasks: Task[] — typed via the declared global
- * ```
- *
- * When no global augmentation exists, `GlobalEntity` falls back to
- * `Record<string, unknown>` — same ergonomics as the legacy untyped
- * overload, with the key still validated against the resolved schema's
- * model keys when that schema is declared.
- */
-export declare function useQuery<K extends GlobalModelKey>(modelKey: K, options?: QueryOptions<GlobalEntity<K>>): GlobalEntity<K>[];
-/** @deprecated Prefer selector reads through `useAblo`. */
-export declare function useQuery<T = Record<string, unknown>>(typename: string, options?: QueryOptions<T>): T[];
-/**
- * Compatibility single-entity lookup. Prefer selector reads:
- *
- * ```ts
- * const task = useAblo((ablo) => ablo.tasks.retrieve(taskId));
- * ```
- *
- * ```ts
- * // Typed
- * const task = useOne(schema, 'tasks', taskId);
- *
- * // Untyped (legacy)
- * const task = useOne(taskId);
- * ```
- */
-/** @deprecated Prefer `useAblo((ablo) => ablo.<model>.retrieve(id))`. */
-export declare function useOne<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K, id?: string): InferModel<S, K> | undefined;
-/** Typed single-entity lookup via the `AbloSync` global augmentation.
- *
- * @deprecated Prefer `useAblo((ablo) => ablo.<model>.retrieve(id))`.
- *
- * The pool `.get(id)` call doesn't actually need the typename at runtime
- * — the return is already keyed by id globally — so the model key serves
- * as a compile-time narrowing hint for consumers who want the specific
- * entity type at the call site. */
-export declare function useOne<K extends GlobalModelKey>(modelKey: K, id?: string): GlobalEntity<K> | undefined;
-/** @deprecated Prefer `useAblo((ablo) => ablo.<model>.retrieve(id))`. */
-export declare function useOne<T = Record<string, unknown>>(id?: string): T | undefined;
-export {};

package/dist/react/useQuery.js

@@ -1,145 +0,0 @@
-'use client';
-import { useMemo, useEffect, useRef, useCallback } from 'react';
-import { useSyncContext } from './context.js';
-import { useReactive } from './useReactive.js';
-// ── Stable key helper ───────────────────────────────────────────────
-/**
- * Produce a stable string key for QueryOptions so useMemo only recreates
- * the view when the logical query changes.
- *
- * - `where` is serialized via JSON.stringify (deterministic for simple values).
- * - `filter` is a function — we track its reference identity.
- * - Primitives (orderBy, order, limit, offset, scope) are included directly.
- */
-function useStableKey(options) {
-    // We use a ref to track the previous filter reference. When it changes
-    // the key changes and the view is recreated.
-    const filterRef = useRef(undefined);
-    // Bump a generation counter when the filter reference changes
-    const genRef = useRef(0);
-    if (options?.filter !== filterRef.current) {
-        filterRef.current = options?.filter;
-        genRef.current++;
-    }
-    return useMemo(() => {
-        if (!options)
-            return '';
-        const parts = [];
-        if (options.where)
-            parts.push('w:' + JSON.stringify(options.where));
-        if (options.filter)
-            parts.push('f:' + genRef.current);
-        if (options.orderBy)
-            parts.push('ob:' + String(options.orderBy));
-        if (options.order)
-            parts.push('o:' + options.order);
-        if (options.limit !== undefined)
-            parts.push('l:' + options.limit);
-        if (options.offset !== undefined)
-            parts.push('off:' + options.offset);
-        if (options.scope)
-            parts.push('s:' + options.scope);
-        return parts.join('|');
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-        options?.where ? JSON.stringify(options.where) : '',
-        genRef.current,
-        options?.orderBy,
-        options?.order,
-        options?.limit,
-        options?.offset,
-        options?.scope,
-    ]);
-}
-// ── Implementation ──────────────────────────────────────────────────
-export function useQuery(schemaOrTypename, modelKeyOrOptions, maybeOptions) {
-    const ctx = useSyncContext();
-    const { store } = ctx;
-    let typename;
-    let options;
-    if (typeof schemaOrTypename === 'string') {
-        // First arg is a string. Could be either the new zero-arg typed
-        // overload (a schema model key, resolved via `ctx.schema`) or the
-        // legacy untyped overload (a raw typename like 'Chat'). When a
-        // schema is present on the context and the string maps to a known
-        // model key, we look up the real typename from the schema's
-        // `ModelDef.typename`. Otherwise we treat the string as a typename
-        // directly — preserving the legacy behavior for any non-opting
-        // consumer. Both paths converge on the same runtime lookup.
-        const key = schemaOrTypename;
-        const ctxSchema = ctx.schema;
-        const modelDef = ctxSchema
-            ? ctxSchema.models[key]
-            : undefined;
-        typename = modelDef?.typename ?? key;
-        options = modelKeyOrOptions;
-    }
-    else {
-        // Explicit schema path: useQuery(schema, 'chats', options?)
-        const schema = schemaOrTypename;
-        const modelKey = modelKeyOrOptions;
-        const modelDef = schema.models[modelKey];
-        typename = modelDef?.typename ?? modelKey;
-        options = maybeOptions;
-    }
-    const optionsKey = useStableKey(options);
-    // The QueryView is generic-erased to `Record<string, unknown>`, but
-    // the caller's filter is typed in `T`. Wrap rather than cast: the
-    // view passes a Record at runtime and the wrapper narrows to T —
-    // single typed boundary, no `as unknown as` chain.
-    const userFilter = options?.filter;
-    const viewOptions = options
-        ? {
-            where: options.where,
-            filter: userFilter
-                ? (entity) => userFilter(entity)
-                : undefined,
-            orderBy: options.orderBy,
-            order: options.order,
-            limit: options.limit,
-            offset: options.offset,
-            scope: options.scope,
-        }
-        : undefined;
-    const view = useMemo(() => store.pool.createView(typename, viewOptions), 
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [store.pool, typename, optionsKey]);
-    useEffect(() => () => view.dispose(), [view]);
-    // Self-subscribing — consumers never wrap their component in
-    // `observer`. `useReactive` tracks the observables read inside the
-    // compute function (`view.results`), recomputes on change, and
-    // returns a stable slice so downstream `.sort()` / `.reverse()`
-    // calls don't trip MobX error 37. The default structural equality
-    // check prevents re-renders when nothing actually moved.
-    //
-    // The compute closure MUST be stable when `view` is stable. Without
-    // useCallback([view]), each render passes a fresh arrow to
-    // useReactive, which then can't distinguish "swapped to a new
-    // QueryView" from "same view, new render" — the wrong call would
-    // either re-subscribe every render (waste) or never re-subscribe
-    // when view actually swaps (stale snapshot bug returning a previous
-    // view's results forever).
-    const compute = useCallback(() => view.results.slice(), [view]);
-    return useReactive(compute);
-}
-export function useOne(schemaOrIdOrKey, modelKeyOrId, maybeId) {
-    const { store } = useSyncContext();
-    if (schemaOrIdOrKey === undefined) {
-        return undefined;
-    }
-    if (typeof schemaOrIdOrKey === 'string') {
-        // Either `useOne(id)` (legacy, one arg) or `useOne(modelKey, id)` (global).
-        // Disambiguate by whether a second arg was passed — both paths
-        // converge on the same runtime pool lookup because entity IDs are
-        // globally unique across model types.
-        if (modelKeyOrId !== undefined) {
-            return store.pool.get(modelKeyOrId);
-        }
-        return store.pool.get(schemaOrIdOrKey);
-    }
-    // Explicit schema path: useOne(schema, 'tasks', id)
-    if (!maybeId)
-        return undefined;
-    return store.pool.get(maybeId);
-}

package/dist/react/useReader.d.ts

@@ -1,69 +0,0 @@
-import type { Schema, InferModel } from '../schema/schema.js';
-import type { ResolveSchema } from '../types/global.js';
-import type { SyncStoreContract } from './context.js';
-type GlobalReaderKey = ResolveSchema extends {
-    models: infer M;
-} ? keyof M & string : string;
-type GlobalReaderActions<K extends string> = ResolveSchema extends Schema ? K extends keyof ResolveSchema['models'] & string ? ReaderActions<ResolveSchema, K> : ReaderActions<Schema, string> : ReaderActions<Schema, string>;
-/**
- * Compatibility schema-typed imperative reader. Returns functions for one-off lookups
- * without subscribing the component to collection changes.
- *
- * Prefer `useAblo()` and call `ablo.<model>.retrieve/list` inside callbacks and
- * effects in new integrations. This hook remains for older string-keyed code.
- *
- * Use this inside event handlers, mutation callbacks, or effects where you
- * need a current snapshot of the pool but don't want to trigger re-renders
- * on every entity change.
- *
- * For reactive reads, use selector reads through
- * `useAblo((ablo) => ablo.<model>.retrieve(id))`.
- *
- * @example
- * import { schema } from '@ablo/schema';
- * import { useReader } from '@abloatai/ablo/react';
- *
- * function useTaskMutations() {
- *   const read = useReader(schema, 'tasks');
- *
- *   return {
- *     create: async (data) => {
- *       // Imperative read — uses FK index when available (O(1))
- *       const existing = read.findMany({ where: { projectId: data.projectId } });
- *       const order = existing.reduce((m, t) => Math.max(m, t.order ?? 0), 0) + 1;
- *       // ...
- *     },
- *   };
- * }
- */
-export interface ReaderFindOptions<T> {
-    /** Equality filter — uses FK index when the field is registered. */
-    where?: Partial<T>;
-    /** Predicate applied AFTER `where` filtering. */
-    filter?: (entity: T) => boolean;
-    /** Sort field. */
-    orderBy?: keyof T & string;
-    /** Sort direction. Default: 'asc'. */
-    order?: 'asc' | 'desc';
-    /** Max results. */
-    limit?: number;
-    /** Skip N results. */
-    offset?: number;
-}
-export interface ReaderActions<S extends Schema, K extends keyof S['models'] & string> {
-    /** Get a single entity by id. Returns undefined if not in pool. */
-    retrieve: (id: string) => InferModel<S, K> | undefined;
-    /** Read a collection with optional filters. Snapshot — not reactive. */
-    list: (options?: ReaderFindOptions<InferModel<S, K>>) => InferModel<S, K>[];
-    /** Count entities matching the options. */
-    count: (options?: ReaderFindOptions<InferModel<S, K>>) => number;
-}
-/**
- * Pure factory — testable without React. `useReader` wraps this in useMemo.
- */
-export declare function createReaderActions<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K, store: SyncStoreContract): ReaderActions<S, K>;
-/** @deprecated Prefer `useAblo()` plus `ablo.<model>.retrieve/list` in callbacks/effects. */
-export declare function useReader<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K): ReaderActions<S, K>;
-/** @deprecated Prefer `useAblo()` plus `ablo.<model>.retrieve/list` in callbacks/effects. */
-export declare function useReader<K extends GlobalReaderKey>(modelKey: K): GlobalReaderActions<K>;
-export {};

package/docs/capabilities.md

@@ -1,163 +0,0 @@
-# Capabilities
-
-A capability is scoped credentials for a non-human actor.
-
-It is not a task and it is not an intent. It is the permission boundary that
-answers who may touch which resources.
-
-Most apps should use `api.agent(...).run(...)`; the SDK creates and revokes the
-capability for that run. Create capabilities directly only for custom runtimes,
-MCP sessions, or protocol-level integrations.
-
-## Why capabilities, not API keys
-
-Static API keys protect a human-operated workflow with one shared secret —
-fine for a server-to-server integration written once and forgotten. They are
-the wrong primitive for AI agents:
-
-- An agent that holds an account-wide key inherits every permission your
-  human team has. A leaked key burns the whole account; a confused-deputy
-  bug lets the agent write to resources it had no business touching.
-- Per-task work needs per-task attribution. One static key across every
-  agent invocation makes the audit trail say "the API key did it" — which
-  tells you nothing about which run, which prompt, or which user delegated
-  the action.
-- Long-lived secrets accumulate blast radius. The longer a credential is
-  valid, the more places it travels (logs, env files, agent prompts), and
-  the wider the leak surface.
-
-Capabilities replace the one-static-key model with **per-run, per-scope,
-short-lived** credentials. The 2025-2026 AI-agent auth consensus (the
-OAuth 2.1 / MCP spec, GCP short-lived credentials, AWS STS AssumeRole,
-HashiCorp Vault leases, Auth0 Token Vault) converged on the same shape:
-issue scoped tokens, attach a TTL, verify per-request, support fast
-revocation. Capabilities are Ablo's instance of that pattern.
-
-## The three-layer security model
-
-Every commit is authorized by three independent checks. None of them is
-sufficient on its own; together they cap the blast radius of every
-credible failure mode.
-
-1. **Lease (TTL)** — every capability has an expiry encoded in the bearer
-   token itself. After the lease, the token decodes but every signature
-   check fails. Caps the damage from a leaked token without requiring a
-   database lookup on the hot path.
-2. **Signature verification (per request)** — every commit re-verifies
-   the token's signature and attenuation. Stateless, cheap (microseconds),
-   detects forged or tampered tokens. The token's `syncGroups` and
-   `operations` are checked against the commit's actual targets;
-   `capability_scope_denied` rejects the request before any write lands.
-3. **Revocation** — `DELETE /v1/capabilities/:id` flips the cap's status
-   server-side; live WebSocket sessions are closed, future requests are
-   rejected within seconds. Closes the gap between lease refresh cycles
-   when you need *immediate* cutoff (compromised agent, accidental
-   over-grant, end-of-trial cleanup).
-
-The mental model: **lease prevents the slow leak, signature verification
-prevents the forged token, revocation prevents the active attacker.**
-Removing any one of the three leaves a class of failure uncovered.
-
-## Why this shape, in one paragraph each
-
-**Lease, not "session"** — A session token requires a database round-trip
-on every request to check liveness. A lease is encoded in the token and
-verified stateless. Vault popularized the term ("lease, renew, revoke");
-the mechanic is the same as AWS STS time-bounded credentials and GCP
-short-lived service-account creds. Ablo uses the word "lease" because the
-bearer holds a *bounded grant*, not just a timer — the same word
-`capability_scope_denied` errors reference.
-
-**Two scope axes (`syncGroups` + `operations`), not one** — `syncGroups`
-narrows *which rows* the actor can see; `operations` narrows *which verbs*
-the actor can use. Collapsing them into one set forces an explosion
-(`tasks.update:org:acme`, `tasks.delete:org:acme`, ...). Keeping them
-orthogonal lets a 3-group × 5-op cap stay 3+5 instead of 3×5. Same shape
-as IAM policies (`Resource` + `Action`), Stripe Restricted Keys
-(`resource_type` + `permission`), and Biscuit caveats.
-
-**Strings from `identityRoles`, never invented** — A consumer who types
-`'org:acme'` literally couples their code to Ablo's identity convention.
-Templates declared once on the schema (see integration-guide.md §1) let
-the convention live in one place; consumers reference it by template, not
-by hand-typing the prefix. Same boundary as Liveblocks' `prepareSession()`
-or PowerSync's named streams: server owns the namespace, client picks a
-subset by id.
-
-**`participantKind` cannot be `'user'`** — Capabilities are explicitly
-for non-human actors. A capability minted as a user would let any code
-path with that bearer impersonate the human; instead, user actions flow
-through session auth (cookies / OAuth) so the audit chain says
-"alice@example.com did X" — not "a token did X." Stripe makes the same
-split between Restricted API Keys (system) and Connect OAuth (user-on-
-behalf-of).
-
-## What capabilities aren't
-
-| Not | Why we didn't ship that |
-|---|---|
-| **A static API key** | One leaked secret = whole-account compromise. No per-run attribution. No automatic expiry. |
-| **An OAuth session token** | OAuth's user-delegation model assumes a human in the loop; agents are the actor, not the delegate. The auth flow round-trips don't fit agent runtimes. |
-| **An opaque DB session** | Per-request DB lookup is the slow path. Stateless verification (signature + lease) is the fast path; the DB is the revocation list, not the live-check. |
-| **A bearer JWT with `exp`** | Conceptually similar, but Biscuit caveats let us *attenuate* a cap further (delegate a narrower sub-scope to a sub-agent) without re-minting. Plain JWTs can't subset themselves. |
-
-## Create
-
-```ts
-import Ablo from '@abloatai/ablo';
-
-const admin = Ablo({ apiKey: process.env.ABLO_API_KEY });
-
-const capability = await admin.capabilities.create({
-  participantKind: 'agent',
-  participantId: 'agent:task-writer',
-  // Identity-anchored groups derived from the schema's `identityRoles`
-  // registration (see integration-guide.md §1). The strings here mirror
-  // whatever templates the schema declared — `org:{id}` and friends for
-  // Ablo's stock schema; a third-party schema with `region:{id}` /
-  // `customer:{id}` roles would pass those instead.
-  syncGroups: ['org:acme', 'user:agent:task-writer'],
-  operations: ['tasks.retrieve', 'tasks.update'],
-  lease: '10m',
-});
-```
-
-Pass `capability.token` into the agent runtime. The agent never sees admin
-credentials.
-
-```ts
-const agent = capability.client();
-```
-
-## Inspect
-
-```ts
-const record = await admin.capabilities.retrieve(capability.id);
-
-record.status; // active | expired | revoked
-record.operations; // ['tasks.retrieve', 'tasks.update']
-```
-
-Inspection never returns the bearer token. Tokens are returned once at create
-time.
-
-## Revoke
-
-```ts
-await admin.capabilities.revoke(capability.id);
-```
-
-Revocation is forward-only. Already accepted commits stand; future requests with
-that token are rejected within seconds.
-
-## Scope Grammar
-
-| Field | Required | Meaning |
-|---|---|---|
-| `participantKind` | yes | `agent` or `system`. Capabilities cannot impersonate `user`. |
-| `participantId` | recommended | Stable actor id, for example `agent:task-writer`. |
-| `syncGroups` | yes | Sync groups the actor can touch. Strings come from the schema's `identityRoles` templates or a model's `syncGroupFormat` — never invented by the caller. |
-| `operations` | yes | Typed operation names, for example `tasks.update`. |
-| `lease` / `leaseSeconds` | recommended | Crash cleanup window for abandoned actors. |
-| `label` | no | Human-readable label for dashboards and audit. |
-| `userMeta` | no | Customer-attested end-user metadata for B2B2C flows. |