@maravilla-labs/platform 0.2.1 → 0.2.4

package/dist/index.d.ts

@@ -1,4 +1,6 @@
+export { a as RenClient, b as RenClientOptions, R as RenEvent, g as getOrCreateClientId, r as renFetch, s as storageDelete, c as storageUpload } from './ren-D0DCQ0Fs.js';
 import { LocalParticipant } from 'livekit-client';
+export { RegisterPushOptions, RegisterPushResult, offsetBefore, registerPush, unregisterPush } from './push.js';
 
 /**
  * Media service for video/audio room management.
@@ -299,6 +301,104 @@ interface Database {
     deleteMany(collection: string, filter: any): Promise<{
         deleted: number;
     }>;
+    /**
+     * Register a vector index on a collection field. Inserts thereafter
+     * will have vectors in `spec.field` synced into an ANN-indexed `vec0`
+     * table inside the same SQLite transaction as the document write.
+     *
+     * Idempotent when the spec matches an existing index; errors on
+     * incompatible re-declaration.
+     *
+     * @example
+     * ```typescript
+     * await db.createVectorIndex('products', {
+     *   field: 'embedding',
+     *   dimensions: 1536,
+     *   metric: 'cosine',
+     *   storage: 'int8',
+     * });
+     * ```
+     */
+    createVectorIndex(collection: string, spec: VectorIndexSpec): Promise<void>;
+    /**
+     * Drop a vector index. Returns `{ removed: true }` if the index existed
+     * and was removed; `{ removed: false }` otherwise. The underlying
+     * collection's documents are untouched.
+     */
+    dropVectorIndex(collection: string, field: string): Promise<{
+        removed: boolean;
+    }>;
+    /** List every registered vector index on a collection. */
+    listVectorIndexes(collection: string): Promise<VectorIndexDescriptor[]>;
+    /**
+     * Pure vector search — convenience wrapper. For hybrid metadata +
+     * vector search, use `find()` with `options.vector`.
+     */
+    findSimilar(collection: string, query: VectorQueryWithFilter): Promise<VectorSearchHit[]>;
+    /**
+     * Register a MongoDB-style secondary index on a collection. Speeds up
+     * `find()` / `findOne()` queries whose filter matches the indexed keys.
+     *
+     * Idempotent when the spec matches an existing index; errors on name
+     * collision with a different spec.
+     *
+     * @example
+     * ```typescript
+     * await db.createIndex('users', { keys: { email: 1 }, unique: true });
+     * await db.createIndex('posts', { keys: { authorId: 1, createdAt: -1 } });
+     * await db.createIndex('sessions', { keys: { createdAt: 1 }, expireAfterSeconds: 3600 });
+     * ```
+     */
+    createIndex(collection: string, spec: IndexSpec): Promise<IndexDescriptor>;
+    /** Drop an index by name. Returns `true` if it existed and was removed. */
+    dropIndex(collection: string, name: string): Promise<{
+        removed: boolean;
+    }>;
+    /**
+     * List every index on a collection — both document indexes and
+     * vector indexes — in a unified response.
+     */
+    listIndexes(collection: string): Promise<IndexDescriptor[]>;
+}
+/** MongoDB-style key direction: `1` = ascending, `-1` = descending. */
+type IndexDirection = 1 | -1;
+/** Whether an index is a regular document index or a vector index. */
+type IndexKind = 'document' | 'vector';
+interface IndexSpec {
+    /** Optional index name. Falls back to an auto-derived name. */
+    name?: string;
+    /**
+     * Key shape. Accepts an ordered array of `[field, direction]` tuples
+     * (recommended) OR a plain object — note that object key order is
+     * language-dependent, so tuples are safer for compound indexes.
+     */
+    keys: Array<[string, IndexDirection]> | Record<string, IndexDirection>;
+    /** Enforce uniqueness across the indexed columns. */
+    unique?: boolean;
+    /**
+     * Partial-index predicate. Only matching documents are included in
+     * the index. Supports `$eq`, `$ne`, `$gt/$gte/$lt/$lte`, `$in/$nin`,
+     * `$exists`, `$and`, `$or`. Rejects `$regex`, `$where`, `$text`.
+     */
+    partial?: Record<string, any>;
+    /** Shorthand for `partial: { <field>: { $exists: true } }`. */
+    sparse?: boolean;
+    /**
+     * TTL in seconds. Requires a single-field index on a Unix-epoch-seconds
+     * field. The platform runs a background sweeper that deletes documents
+     * older than this.
+     */
+    expireAfterSeconds?: number;
+}
+interface IndexDescriptor {
+    collection: string;
+    name: string;
+    keys: Array<[string, IndexDirection]>;
+    unique: boolean;
+    sparse: boolean;
+    partial?: Record<string, any>;
+    expireAfterSeconds?: number;
+    kind: IndexKind;
 }
 /**
  * Options for database find operations.
@@ -311,7 +411,81 @@ interface DbFindOptions {
     skip?: number;
     /** Sort order specification (MongoDB-style: { field: 1 } for ascending, { field: -1 } for descending) */
     sort?: any;
+    /**
+     * Vector search clause. When set, `find()` performs a hybrid
+     * metadata + vector search using the collection's registered vector
+     * index on `vector.field`. The metadata filter in `filter` is applied
+     * after (or alongside, depending on the index type) the vector ranking.
+     */
+    vector?: VectorQuery;
+}
+/** Distance metric used to compare vectors. */
+type VectorMetric = 'cosine' | 'l2' | 'hamming';
+/**
+ * On-disk storage precision for vectors.
+ * - `float32` (default): 4 bytes per dim, highest accuracy
+ * - `int8`: 1 byte per dim, 4× smaller, <2% accuracy loss for most embeddings
+ * - `bit`: 1 bit per dim, 32× smaller; requires metric='hamming'
+ */
+type VectorStorage = 'float32' | 'int8' | 'bit';
+/** Query shape: single vector or an array of vectors (ColBERT-style). */
+type VectorQueryMode = 'single' | 'late-interaction';
+/** How multi-vector distances are aggregated per document. */
+type VectorAggregation = 'max-sim' | 'sum';
+interface VectorIndexSpec {
+    /** JSON path of the vector field inside each document (dotted syntax OK). */
+    field: string;
+    /** Stored vector dimensionality. */
+    dimensions: number;
+    /** Distance metric; defaults to `cosine`. */
+    metric?: VectorMetric;
+    /** Storage precision; defaults to `float32`. Int8/bit quantize automatically on insert. */
+    storage?: VectorStorage;
+    /** Allow queries with vectors shorter than `dimensions`. Requires matryoshka-trained embeddings. */
+    matryoshka?: boolean;
+    /** Each document holds an array of vectors (one per chunk/token). */
+    multiVector?: boolean;
+}
+interface VectorIndexDescriptor {
+    collection: string;
+    field: string;
+    dimensions: number;
+    metric: VectorMetric;
+    storage: VectorStorage;
+    matryoshka: boolean;
+    multiVector: boolean;
+}
+interface VectorQuery {
+    /** Must match a registered vector index field on the collection. */
+    field: string;
+    /**
+     * Query vector (`number[]` for `queryMode: 'single'`) or array of
+     * query vectors (`number[][]` for `queryMode: 'late-interaction'`).
+     */
+    value: number[] | number[][];
+    /** Top-k result count. Must be > 0. */
+    k: number;
+    /** Per-query metric override. Defaults to the index's configured metric. */
+    metric?: VectorMetric;
+    /** Drop results below this normalized score (0–1, higher = more similar). */
+    minScore?: number;
+    /** Defaults to `single`. */
+    queryMode?: VectorQueryMode;
+    /** Defaults to `max-sim`. Only meaningful for multi-vector indexes. */
+    aggregation?: VectorAggregation;
 }
+/** Convenience shape for the pure-vector `findSimilar()` helper. */
+interface VectorQueryWithFilter extends VectorQuery {
+    /** Optional metadata filter applied alongside the vector search. */
+    filter?: any;
+    /** Overall result cap (defaults to `k`). */
+    limit?: number;
+}
+/** Document returned from a vector search, with similarity metadata attached. */
+type VectorSearchHit = Record<string, any> & {
+    _score: number;
+    _distance: number;
+};
 /**
  * Storage interface for object/file storage operations.
  * Provides S3-compatible API for storing and retrieving files.
@@ -343,7 +517,7 @@ interface DbFindOptions {
  * Source types accepted by Storage.putStream for streaming uploads.
  */
 type StoragePutStreamSource = Uint8Array | ArrayBuffer | string | Blob | ReadableStream<Uint8Array | ArrayBuffer | string | number[]> | Iterable<Uint8Array | ArrayBuffer | string | number[]> | AsyncIterable<Uint8Array | ArrayBuffer | string | number[]>;
-interface Storage$1 {
+interface Storage {
     /**
      * Generate a presigned URL for uploading a file directly from the browser.
      *
@@ -555,7 +729,7 @@ interface PlatformEnv {
     /** Database interface for document operations */
     DB: Database;
     /** Object/file storage interface */
-    STORAGE: Storage$1;
+    STORAGE: Storage;
 }
 /**
  * Main platform interface providing access to all Maravilla runtime services.
@@ -621,6 +795,25 @@ interface AuthUser {
     /** Unix timestamp of last login (if any) */
     last_login_at?: number;
 }
+/**
+ * Snapshot of whoever is currently bound to the request as the caller.
+ *
+ * Populated by {@link AuthService.login} (implicit), {@link AuthService.setCurrentUser}
+ * (explicit), or left anonymous if neither has run for this request.
+ * This is exactly what per-resource policies see as `auth.*` when they run.
+ */
+interface AuthCaller {
+    /** Caller's user id, or `""` if anonymous */
+    user_id: string;
+    /** Caller's email, or `""` if anonymous */
+    email: string;
+    /** Admin flag from the session */
+    is_admin: boolean;
+    /** Role names (project-scoped) */
+    roles: string[];
+    /** `true` when no identity is bound to this request */
+    is_anonymous: boolean;
+}
 /**
  * Session returned after successful login or token refresh.
  */
@@ -869,6 +1062,270 @@ interface AuthService {
     withAuth<T extends (request: Request & {
         user: AuthUser;
     }) => Promise<Response>>(handler: T): (request: Request) => Promise<Response>;
+    /**
+     * Explicitly bind the caller for the remainder of this request.
+     * Pass a JWT to validate + bind, or `null` / `""` to clear.
+     *
+     * `login()` already binds implicitly on success; reach for `setCurrentUser`
+     * when you receive a JWT from an inbound `Authorization` header or cookie
+     * and want subsequent KV/DB/realtime/media ops to run as that user.
+     *
+     * Not available on remote clients — throws.
+     */
+    setCurrentUser(token: string | null): Promise<void>;
+    /**
+     * Snapshot of the currently bound caller. Returns an anonymous caller
+     * (`is_anonymous: true`) when no identity has been bound.
+     *
+     * Not available on remote clients — throws.
+     */
+    getCurrentUser(): AuthCaller;
+    /**
+     * Ask the policy engine whether the bound caller would be allowed to
+     * perform `action` on `resourceId`, given the supplied `node` payload.
+     * Returns a boolean — never throws on denial.
+     *
+     * The check runs the exact same evaluator that gates direct KV/DB/
+     * realtime/media ops, so `can(...)` is authoritative.
+     *
+     * @example
+     * ```typescript
+     * const ok = await platform.auth.can("delete", "documents", {
+     *   owner: doc.owner,
+     *   status: doc.status,
+     * });
+     * if (!ok) return new Response("Forbidden", { status: 403 });
+     * ```
+     *
+     * Not available on remote clients — throws.
+     */
+    can(action: string, resourceId: string, node?: Record<string, unknown> | null): Promise<boolean>;
+}
+/**
+ * Per-request opt-out toggle for the Layer 2 policy evaluator.
+ *
+ * Flipping `setEnabled(false)` disables **per-resource policies only** for
+ * the remainder of the current request. Layer 1 (tenant + owner isolation)
+ * is always enforced — no call can ever escape its tenant. Every flip is
+ * audit-logged server-side with the caller's identity.
+ *
+ * Intended for trusted in-app flows (first-run seeders, admin jobs). Do not
+ * toggle based on untrusted input.
+ *
+ * Not available on remote clients — throws.
+ */
+interface PolicyService {
+    /** Disable or re-enable Layer 2 policy checks for this request. */
+    setEnabled(enabled: boolean): void;
+    /** `true` when Layer 2 is active for this request. */
+    isEnabled(): boolean;
+}
+/**
+ * Target selector for Web Push sends. Combine fields to narrow — all
+ * specified conditions must match for a subscription to receive the push.
+ *
+ * @example
+ * ```typescript
+ * // Every subscription tagged with "waitlist"
+ * await platform.push.send({ topic: 'waitlist' }, notification);
+ *
+ * // Every device belonging to one authenticated user
+ * await platform.push.send({ userId: 'u_42' }, notification);
+ *
+ * // "This specific user's subscription for this specific invite"
+ * await platform.push.send({ userId: 'u_42', topic: 'invite:abc:rsvp' }, notification);
+ * ```
+ */
+interface PushTarget {
+    userId?: string;
+    visitorId?: string;
+    topic?: string;
+    userIds?: string[];
+    topics?: string[];
+    onlyActive?: boolean;
+}
+/** Shape of a Web Push notification payload. */
+interface NotificationPayload {
+    /** Required — the notification headline shown on lock screens and the notification shade. */
+    title: string;
+    body?: string;
+    icon?: string;
+    badge?: string;
+    image?: string;
+    /** Browsers dedupe notifications sharing a tag. */
+    tag?: string;
+    /** Where to navigate when the notification is clicked. */
+    url?: string;
+    /** Arbitrary JSON delivered to the service worker alongside the notification. */
+    data?: Record<string, unknown>;
+    /** Seconds the push service holds the message if the device is offline. */
+    ttl?: number;
+    urgency?: 'very-low' | 'low' | 'normal' | 'high';
+}
+/**
+ * Options for `platform.push.schedule(...)`.
+ *
+ * @example
+ * ```typescript
+ * // Remind every RSVP'd guest one hour before the event.
+ * await platform.push.schedule(
+ *   { topic: `invite:${invite.id}` },
+ *   { title: invite.title, body: 'Your event is in one hour' },
+ *   {
+ *     at: offsetBefore(invite.event_date, '1h'),
+ *     key: `invite:${invite.id}:reminder-1h`,
+ *   }
+ * );
+ * ```
+ */
+interface ScheduleOptions {
+    /**
+     * When to send. Absolute `Date` or ISO-8601 string; the server treats
+     * bare (no-offset) strings as UTC.
+     */
+    at: Date | string;
+    /**
+     * Idempotency key scoped to your project. Re-calling `schedule` with the
+     * same key atomically replaces the prior pending job — safe to call on
+     * every save of an invite whose event date may change.
+     */
+    key: string;
+    /** Maximum delivery attempts before the job is marked failed. Defaults to 3. */
+    maxAttempts?: number;
+    /**
+     * If set, the job re-queues after every successful send and fires again
+     * this many seconds later. Use for daily digests (`86400`), weekly
+     * updates (`604800`), or any fixed-interval loop. `cancelScheduled(key)`
+     * stops the loop.
+     */
+    everySeconds?: number;
+}
+/** A single scheduled push job as returned by `listScheduled` / `getScheduled`. */
+interface ScheduledJob {
+    jobId: string;
+    key?: string;
+    /** Next fire time — unix seconds. Convert with `new Date(scheduledFor * 1000)`. */
+    scheduledFor: number;
+    status: 'pending' | 'running' | 'succeeded' | 'failed';
+    attempts: number;
+    maxAttempts: number;
+    lastError?: string;
+    createdAt: number;
+    updatedAt: number;
+    /** Populated once the job has fired at least once. */
+    sentAt?: number;
+    /** Set when the job recurs — `schedule()` was called with `everySeconds`. */
+    recurringIntervalSecs?: number;
+}
+/** Filter passed to `listScheduled`. */
+interface ListScheduledFilter {
+    status?: 'pending' | 'running' | 'succeeded' | 'failed';
+    limit?: number;
+    offset?: number;
+}
+/** Counts by status, as returned by `queueStats`. */
+interface QueueStats {
+    pending: number;
+    running: number;
+    succeeded: number;
+    failed: number;
+}
+/** Outcome of a single `platform.push.send(...)` fan-out. */
+interface SendReport {
+    attempted: number;
+    succeeded: number;
+    gone: number;
+    failed: number;
+    errors?: Array<{
+        subscriptionId: string;
+        message: string;
+    }>;
+}
+/** Shape of a stored Web Push subscription. */
+interface StoredPushSubscription {
+    id: string;
+    provider: 'web-push' | 'apns' | 'fcm';
+    endpoint: string;
+    p256dh?: string | null;
+    auth?: string | null;
+    userId?: string | null;
+    visitorId?: string | null;
+    userAgent?: string | null;
+    topics: string[];
+    createdAt: number;
+    lastSeenAt?: number | null;
+    expiresAt?: number | null;
+    isActive: boolean;
+}
+/** Aggregate counts across every subscription in the project. */
+interface SubscriptionCounts {
+    total: number;
+    byTopic: Array<[string, number]>;
+    byProvider: Array<[string, number]>;
+}
+/** Public VAPID config for the current project. */
+interface PublicPushConfig {
+    vapidPublic: string;
+    contactEmail: string;
+    updatedAt: number;
+}
+/**
+ * Server-side Web Push service. Access via `platform.push` inside your
+ * runtime code.
+ */
+interface PushService {
+    /**
+     * Fan out a notification to every active subscription matching `target`.
+     * Blocks until every device has been tried.
+     */
+    send(target: PushTarget, notification: NotificationPayload): Promise<SendReport>;
+    /**
+     * Fire-and-forget variant. The request handler can return immediately;
+     * the dispatch continues in the background. Best-effort — a delivery
+     * restart mid-dispatch loses in-flight sends.
+     */
+    sendBackground(target: PushTarget, notification: NotificationPayload): Promise<void>;
+    /**
+     * Queue a notification for a future time. Idempotent by `key` — repeated
+     * calls with the same key replace the prior pending job. Set `everySeconds`
+     * for recurring digests.
+     */
+    schedule(target: PushTarget, notification: NotificationPayload, opts: ScheduleOptions): Promise<{
+        jobId: string;
+    }>;
+    /** Cancel the pending scheduled job with this idempotency key. */
+    cancelScheduled(key: string): Promise<{
+        canceled: number;
+    }>;
+    /** List scheduled jobs for this project, optionally filtered by status. */
+    listScheduled(filter?: ListScheduledFilter): Promise<ScheduledJob[]>;
+    /** Look up a single scheduled job by idempotency key. */
+    getScheduled(key: string): Promise<ScheduledJob | null>;
+    /** Per-status counts for the scheduled queue. */
+    queueStats(): Promise<QueueStats>;
+    /** List subscriptions — useful for admin UIs and debugging. */
+    list(filter?: {
+        topic?: string;
+        userId?: string;
+        visitorId?: string;
+        onlyActive?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<StoredPushSubscription[]>;
+    /** Aggregate counts grouped by topic and provider. */
+    counts(): Promise<SubscriptionCounts>;
+    /** Remove a subscription by id. */
+    unsubscribe(subscriptionId: string): Promise<void>;
+    /** Remove a subscription by its push service endpoint URL. */
+    unsubscribeByEndpoint(endpoint: string): Promise<void>;
+    /** Fetch the project's current VAPID public key + contact email. */
+    getVapidConfig(): Promise<PublicPushConfig>;
+    /**
+     * Rotate the project's VAPID keypair. **Every existing subscription
+     * silently stops working** — browsers bind subscriptions to the key they
+     * saw at subscribe time. Confirm with your users before calling.
+     */
+    rotateVapidKeys(): Promise<PublicPushConfig>;
 }
 interface Platform {
     /** Environment containing all available platform services */
@@ -877,57 +1334,19 @@ interface Platform {
     media?: MediaService;
     /** Realtime service for pub/sub channels and presence */
     realtime: RealtimeService;
-    /** Auth service for end-user authentication and user management */
+    /** Auth service for end-user authentication, identity binding, and authorization checks */
     auth: AuthService;
+    /** Per-request Layer 2 policy toggle (Layer 1 isolation always applies) */
+    policy: PolicyService;
+    /**
+     * Web Push — send, schedule, or query browser push notifications for
+     * logged-in users and anonymous visitors. Available when Push is enabled
+     * in project settings; `undefined` when running against the dev-server
+     * fallback that doesn't proxy to delivery.
+     */
+    push?: PushService;
 }
 
-interface RenEvent {
-    t: string;
-    r: string;
-    k?: string;
-    v?: string;
-    ts?: number;
-    src?: string;
-    ns?: string;
-    ch?: string;
-    data?: any;
-    uid?: string;
-    [extra: string]: any;
-}
-interface RenClientOptions {
-    endpoint?: string;
-    subscriptions?: string[];
-    clientId?: string;
-    autoReconnect?: boolean;
-    maxBackoffMs?: number;
-    debug?: boolean;
-}
-type Listener = (event: RenEvent) => void;
-declare class RenClient {
-    private endpoint;
-    private subs;
-    private clientId;
-    private listeners;
-    private es;
-    private closed;
-    private attempt;
-    private autoReconnect;
-    private maxBackoff;
-    private debug;
-    constructor(opts?: RenClientOptions);
-    private detectEndpoint;
-    private log;
-    private buildUrl;
-    private connect;
-    on(listener: Listener): () => void;
-    getClientId(): string;
-    close(): void;
-}
-declare function getOrCreateClientId(storage?: Storage): string;
-declare function renFetch(input: string | URL | Request, init?: RequestInit, clientId?: string): Promise<Response>;
-declare function storageUpload(path: string, file: Blob | File, clientId?: string): Promise<any>;
-declare function storageDelete(path: string, clientId?: string): Promise<any>;
-
 interface RealtimeEvent {
     event: string;
     channel: string;
@@ -1241,4 +1660,4 @@ declare function getPlatform(options?: {
  */
 declare function clearPlatformCache(): void;
 
-export { type AuthField, type AuthService, type AuthSession, type AuthUser, type Database, type DbFindOptions, type KvListResult, type KvNamespace, type LoginOptions, MediaLocalParticipant, type MediaParticipant, type MediaParticipantInfo, MediaRoom, MediaRoomEvent, type MediaRoomInfo, type MediaRoomInfoSettings, type MediaRoomOptions, type MediaService, type MediaTokenResult, type MediaTrackPublication, type Platform, type PlatformEnv, type PresenceMember, type PresenceService, RealtimeClient, type RealtimeClientOptions, type RealtimeEvent, type RealtimeService, type RegisterOptions, RemoteMediaService, RenClient, type RenClientOptions, type RenEvent, type Storage$1 as Storage, type StoragePutStreamSource, type TrackKind, type TrackSource, type UpdateUserOptions, type UserListFilter, type UserListResponse, type VideoResolution, attachTrack, clearPlatformCache, detachTrack, getOrCreateClientId, getPlatform, renFetch, storageDelete, storageUpload };
+export { type AuthCaller, type AuthField, type AuthService, type AuthSession, type AuthUser, type Database, type DbFindOptions, type IndexDescriptor, type IndexDirection, type IndexKind, type IndexSpec, type KvListResult, type KvNamespace, type ListScheduledFilter, type LoginOptions, MediaLocalParticipant, type MediaParticipant, type MediaParticipantInfo, MediaRoom, MediaRoomEvent, type MediaRoomInfo, type MediaRoomInfoSettings, type MediaRoomOptions, type MediaService, type MediaTokenResult, type MediaTrackPublication, type NotificationPayload, type Platform, type PlatformEnv, type PolicyService, type PresenceMember, type PresenceService, type PublicPushConfig, type PushService, type PushTarget, type QueueStats, RealtimeClient, type RealtimeClientOptions, type RealtimeEvent, type RealtimeService, type RegisterOptions, RemoteMediaService, type ScheduleOptions, type ScheduledJob, type SendReport, type Storage, type StoragePutStreamSource, type StoredPushSubscription, type SubscriptionCounts, type TrackKind, type TrackSource, type UpdateUserOptions, type UserListFilter, type UserListResponse, type VectorAggregation, type VectorIndexDescriptor, type VectorIndexSpec, type VectorMetric, type VectorQuery, type VectorQueryMode, type VectorQueryWithFilter, type VectorSearchHit, type VectorStorage, type VideoResolution, attachTrack, clearPlatformCache, detachTrack, getPlatform };