@maravilla-labs/types 0.2.0 → 0.2.2

package/index.ts

@@ -83,6 +83,87 @@ export interface KvStore {
 
 // Database Types
 
+/** 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 {
+  name?: string;
+  keys: Array<[string, IndexDirection]> | Record<string, IndexDirection>;
+  unique?: boolean;
+  sparse?: boolean;
+  partial?: Record<string, unknown>;
+  expireAfterSeconds?: number;
+}
+
+export interface IndexDescriptor {
+  collection: string;
+  name: string;
+  keys: Array<[string, IndexDirection]>;
+  unique: boolean;
+  sparse: boolean;
+  partial?: Record<string, unknown>;
+  expireAfterSeconds?: number;
+  kind: IndexKind;
+}
+
+/** Distance metric used to compare vectors. */
+export type VectorMetric = 'cosine' | 'l2' | 'hamming';
+
+/**
+ * On-disk storage precision for vectors.
+ * - `float32` (default): 4 bytes per dim
+ * - `int8`: 1 byte per dim, 4× smaller, typically <2% accuracy loss
+ * - `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';
+
+/** Spec used to declare a vector index on a collection field. */
+export interface VectorIndexSpec {
+  field: string;
+  dimensions: number;
+  metric?: VectorMetric;
+  storage?: VectorStorage;
+  matryoshka?: boolean;
+  multiVector?: boolean;
+}
+
+/** Metadata for a registered vector index. */
+export interface VectorIndexDescriptor {
+  collection: string;
+  field: string;
+  dimensions: number;
+  metric: VectorMetric;
+  storage: VectorStorage;
+  matryoshka: boolean;
+  multiVector: boolean;
+}
+
+/** Vector search clause riding inside DbFindOptions. */
+export interface VectorQuery {
+  field: string;
+  value: number[] | number[][];
+  k: number;
+  metric?: VectorMetric;
+  minScore?: number;
+  queryMode?: VectorQueryMode;
+  aggregation?: VectorAggregation;
+}
+
+/** Document returned by a vector search with similarity metadata attached. */
+export type VectorSearchHit = Record<string, any> & {
+  _score: number;
+  _distance: number;
+};
+
 /**
  * Database find options
  */
@@ -91,6 +172,8 @@ export interface DbFindOptions {
   skip?: number;
   sort?: Record<string, 1 | -1>;
   projection?: Record<string, 1 | 0>;
+  /** Hybrid metadata + vector search clause. */
+  vector?: VectorQuery;
 }
 
 /**
@@ -234,6 +317,138 @@ export interface Storage {
   getMetadata(key: string): Promise<StorageMetadata>;
 }
 
+// Stewardship Types
+
+/** Delegation mode for stewardship overrides */
+export type DelegationMode = 'full' | 'scoped';
+
+/** Status of a stewardship override */
+export type StewardshipStatus = 'active' | 'suspended' | 'revoked' | 'expired';
+
+/** A scoped permission entry */
+export interface ScopedPermission {
+  /** Resource name */
+  resource: string;
+  /** Allowed actions on the resource */
+  actions: string[];
+}
+
+/** A stewardship override record */
+export interface StewardshipOverride {
+  id: string;
+  steward_id: string;
+  ward_id: string;
+  delegation_mode: DelegationMode;
+  scoped_permissions: ScopedPermission[];
+  valid_from?: number;
+  valid_until?: number;
+  status: StewardshipStatus;
+  reason?: string;
+  source: string;
+  source_circle_id?: string;
+  source_relation_type_id?: string;
+  created_at: number;
+  updated_at: number;
+}
+
+/** Options for creating a stewardship override */
+export interface CreateStewardshipOverrideRequest {
+  steward_id: string;
+  ward_id: string;
+  delegation_mode?: DelegationMode;
+  scoped_permissions?: ScopedPermission[];
+  valid_from?: number;
+  valid_until?: number;
+  reason?: string;
+}
+
+/** Result of resolving stewardship for a user */
+export interface StewardshipResolution {
+  /** Users who are stewards of this user */
+  stewards: StewardshipOverride[];
+  /** Users this user is a steward of */
+  wards: StewardshipOverride[];
+}
+
+/** Context for acting as another user */
+export interface ActAsContext {
+  steward_id: string;
+  ward_id: string;
+  delegation_mode: DelegationMode;
+  scoped_permissions: ScopedPermission[];
+  session_token: string;
+  expires_at: number;
+}
+
+/** An entry in the stewardship audit log */
+export interface StewardshipAuditEntry {
+  id: string;
+  performed_by: string;
+  on_behalf_of: string;
+  action: string;
+  resource?: string;
+  details?: Record<string, any>;
+  created_at: number;
+}
+
+/** Options for listing audit log entries */
+export interface AuditListOptions {
+  limit?: number;
+  offset?: number;
+}
+
+/** Stewardship service interface */
+export interface Stewardship {
+  resolve(userId: string): Promise<StewardshipResolution>;
+  createOverride(options: CreateStewardshipOverrideRequest): Promise<StewardshipOverride>;
+  revoke(id: string): Promise<void>;
+  checkPermission(stewardId: string, wardId: string, resource: string, action: string): Promise<boolean>;
+  createActAs(stewardId: string, wardId: string): Promise<ActAsContext>;
+  listAudit(userId: string, options?: AuditListOptions): Promise<StewardshipAuditEntry[]>;
+}
+
+// Resource Types
+
+/** A platform resource definition */
+export interface Resource {
+  id: string;
+  resource_name: string;
+  title: string;
+  description?: string;
+  actions: string[];
+  created_at: number;
+  updated_at: number;
+}
+
+/** Options for creating a resource */
+export interface CreateResourceRequest {
+  resource_name: string;
+  title: string;
+  description?: string;
+  actions?: string[];
+}
+
+// Circle Types
+
+/** Circle membership entry */
+export interface CircleMembership {
+  user_id: string;
+  email: string;
+  relationship: string;
+  is_primary_contact: boolean;
+  joined_at: number;
+}
+
+/** A circle */
+export interface Circle {
+  id: string;
+  name: string;
+  metadata?: Record<string, any>;
+  member_count: number;
+  created_at: number;
+  updated_at: number;
+}
+
 // Platform Types
 
 /**
@@ -246,6 +461,39 @@ export interface Platform {
   db: Database;
   /** Storage service instance */
   storage: Storage;
+  /** Auth service with stewardship, resources, and circle helpers */
+  auth: {
+    register(options: { email: string; password: string; profile?: Record<string, any> }): Promise<any>;
+    login(options: { email: string; password: string }): Promise<any>;
+    validate(accessToken: string): Promise<any>;
+    refresh(refreshToken: string): Promise<any>;
+    logout(sessionId: string): Promise<void>;
+    getUser(userId: string): Promise<any>;
+    listUsers(filter?: Record<string, any>): Promise<any>;
+    updateUser(userId: string, update: Record<string, any>): Promise<any>;
+    deleteUser(userId: string): Promise<void>;
+    sendVerification(userId: string): Promise<any>;
+    verifyEmail(token: string): Promise<void>;
+    sendPasswordReset(email: string): Promise<any>;
+    resetPassword(token: string, newPassword: string): Promise<void>;
+    changePassword(userId: string, oldPassword: string, newPassword: string): Promise<void>;
+    getFieldConfig(): Promise<any>;
+    getOAuthUrl(provider: string, options?: { redirectUri?: string }): Promise<any>;
+    handleOAuthCallback(provider: string, params: { code: string; state: string }): Promise<any>;
+
+    /** Stewardship (guardian/ward delegation) */
+    stewardship: Stewardship;
+
+    /** List available resources */
+    listResources(): Promise<Resource[]>;
+    /** Create a resource definition */
+    createResource(options: CreateResourceRequest): Promise<Resource>;
+
+    /** Get circle members */
+    getCircleMembers(circleId: string): Promise<CircleMembership[]>;
+    /** Get circles a user belongs to */
+    getUserCircles(userId: string): Promise<Circle[]>;
+  };
   /** Legacy aliases for compatibility */
   env: {
     KV: KvStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/types",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "TypeScript definitions for Maravilla Runtime platform APIs",
   "main": "index.ts",
   "types": "index.ts",