@maravilla-labs/platform 0.2.0 → 0.2.2

package/src/types.ts

@@ -248,6 +248,111 @@ export 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. */
+export type IndexDirection = 1 | -1;
+
+/** Whether an index is a regular document index or a vector index. */
+export type IndexKind = 'document' | 'vector';
+
+export 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;
+}
+
+export interface IndexDescriptor {
+  collection: string;
+  name: string;
+  keys: Array<[string, IndexDirection]>;
+  unique: boolean;
+  sparse: boolean;
+  partial?: Record<string, any>;
+  expireAfterSeconds?: number;
+  kind: IndexKind;
 }
 
 /**
@@ -261,8 +366,91 @@ export 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. */
+export 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'
+ */
+export type VectorStorage = 'float32' | 'int8' | 'bit';
+
+/** Query shape: single vector or an array of vectors (ColBERT-style). */
+export type VectorQueryMode = 'single' | 'late-interaction';
+
+/** How multi-vector distances are aggregated per document. */
+export type VectorAggregation = 'max-sim' | 'sum';
+
+export 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;
+}
+
+export interface VectorIndexDescriptor {
+  collection: string;
+  field: string;
+  dimensions: number;
+  metric: VectorMetric;
+  storage: VectorStorage;
+  matryoshka: boolean;
+  multiVector: boolean;
+}
+
+export 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. */
+export 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. */
+export 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.
@@ -585,6 +773,26 @@ export interface AuthUser {
   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.
+ */
+export 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.
  */
@@ -840,6 +1048,302 @@ export interface AuthService {
   withAuth<T extends (request: Request & { user: AuthUser }) => Promise<Response>>(
     handler: T
   ): (request: Request) => Promise<Response>;
+
+  // ── Request-scoped identity + authorization ──
+  //
+  // These methods operate on the **current request's** caller context.
+  // They're meaningful inside the platform runtime (one isolate serving a
+  // Deno request). When called from a remote client — code running outside
+  // the runtime — they throw, because there is no per-request context to
+  // bind.
+
+  /**
+   * 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.
+ */
+export 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);
+ * ```
+ */
+export interface PushTarget {
+  userId?: string;
+  visitorId?: string;
+  topic?: string;
+  userIds?: string[];
+  topics?: string[];
+  onlyActive?: boolean;
+}
+
+/** Shape of a Web Push notification payload. */
+export 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`,
+ *   }
+ * );
+ * ```
+ */
+export 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`. */
+export 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`. */
+export interface ListScheduledFilter {
+  status?: 'pending' | 'running' | 'succeeded' | 'failed';
+  limit?: number;
+  offset?: number;
+}
+
+/** Counts by status, as returned by `queueStats`. */
+export interface QueueStats {
+  pending: number;
+  running: number;
+  succeeded: number;
+  failed: number;
+}
+
+/** Outcome of a single `platform.push.send(...)` fan-out. */
+export interface SendReport {
+  attempted: number;
+  succeeded: number;
+  gone: number;
+  failed: number;
+  errors?: Array<{ subscriptionId: string; message: string }>;
+}
+
+/** Shape of a stored Web Push subscription. */
+export 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. */
+export interface SubscriptionCounts {
+  total: number;
+  byTopic: Array<[string, number]>;
+  byProvider: Array<[string, number]>;
+}
+
+/** Public VAPID config for the current project. */
+export interface PublicPushConfig {
+  vapidPublic: string;
+  contactEmail: string;
+  updatedAt: number;
+}
+
+/**
+ * Server-side Web Push service. Access via `platform.push` inside your
+ * runtime code.
+ */
+export 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>;
 }
 
 export interface Platform {
@@ -849,6 +1353,15 @@ export interface Platform {
   media?: import('./media.js').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;
 }

package/tsup.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'tsup';
 
 export default defineConfig({
-  entry: ['src/index.ts'],
+  entry: ['src/index.ts', 'src/config.ts', 'src/push.ts', 'src/events.ts'],
   format: ['esm'],
   dts: true,
   splitting: false,