@maravilla-labs/platform 0.1.34 → 0.2.0

package/dist/index.d.ts

@@ -598,6 +598,278 @@ interface PresenceService {
         lastSeen?: number;
     }>>;
 }
+/**
+ * Authenticated user record from the platform auth service.
+ */
+interface AuthUser {
+    /** Unique user ID (prefixed with "usr_") */
+    id: string;
+    /** User's email address */
+    email: string;
+    /** Whether the email has been verified */
+    email_verified: boolean;
+    /** Account status */
+    status: 'active' | 'suspended' | 'deactivated';
+    /** Authentication provider ("email", "google", "github", etc.) */
+    provider: string;
+    /** Group IDs the user belongs to */
+    groups: string[];
+    /** Unix timestamp when the user was created */
+    created_at: number;
+    /** Unix timestamp when the user was last updated */
+    updated_at: number;
+    /** Unix timestamp of last login (if any) */
+    last_login_at?: number;
+}
+/**
+ * Session returned after successful login or token refresh.
+ */
+interface AuthSession {
+    /** Short-lived JWT access token (default 15 min) */
+    access_token: string;
+    /** Single-use opaque refresh token (default 30 days) */
+    refresh_token: string;
+    /** Access token lifetime in seconds */
+    expires_in: number;
+    /** The authenticated user */
+    user: AuthUser;
+}
+/**
+ * Custom registration field defined in project auth settings.
+ */
+interface AuthField {
+    /** Field key (used as form field name) */
+    key: string;
+    /** Display label */
+    label: string;
+    /** Field type: text, email, phone, date, number, select, boolean, url, textarea */
+    field_type: string;
+    /** Whether the field is required */
+    required: boolean;
+    /** Whether the field appears on the registration form */
+    show_on_register: boolean;
+}
+/**
+ * Options for registering a new user.
+ */
+interface RegisterOptions {
+    /** User's email address */
+    email: string;
+    /** Password (minimum 8 characters) */
+    password: string;
+    /** Optional profile data (custom fields) */
+    profile?: Record<string, any>;
+}
+/**
+ * Options for logging in.
+ */
+interface LoginOptions {
+    /** User's email address */
+    email: string;
+    /** User's password */
+    password: string;
+}
+/**
+ * Filter options for listing users.
+ */
+interface UserListFilter {
+    /** Max results per page (default 50) */
+    limit?: number;
+    /** Number of results to skip */
+    offset?: number;
+    /** Filter by account status */
+    status?: 'active' | 'suspended' | 'deactivated';
+    /** Filter by email (partial match) */
+    email_contains?: string;
+    /** Filter by group ID */
+    group_id?: string;
+}
+/**
+ * Paginated user list response.
+ */
+interface UserListResponse {
+    /** Users in this page */
+    users: AuthUser[];
+    /** Total number of matching users */
+    total: number;
+    /** Page size */
+    limit: number;
+    /** Offset */
+    offset: number;
+}
+/**
+ * Options for updating a user.
+ */
+interface UpdateUserOptions {
+    /** New email address */
+    email?: string;
+    /** New status */
+    status?: 'active' | 'suspended' | 'deactivated';
+    /** Profile data to merge */
+    profile?: Record<string, any>;
+}
+/**
+ * Auth service for end-user authentication and user management.
+ *
+ * @example
+ * ```typescript
+ * const platform = getPlatform();
+ *
+ * // Register a new user
+ * const user = await platform.auth.register({
+ *   email: 'user@example.com',
+ *   password: 'securePassword123'
+ * });
+ *
+ * // Login
+ * const session = await platform.auth.login({
+ *   email: 'user@example.com',
+ *   password: 'securePassword123'
+ * });
+ * // session.access_token — short-lived JWT
+ * // session.refresh_token — single-use refresh token
+ *
+ * // Validate a token (e.g. from Authorization header or cookie)
+ * const user = await platform.auth.validate(session.access_token);
+ *
+ * // Protect a route with withAuth middleware
+ * export default {
+ *   fetch: platform.auth.withAuth(async (request) => {
+ *     // request.user is guaranteed to be set
+ *     return new Response(`Hello ${request.user.email}`);
+ *   })
+ * };
+ * ```
+ */
+interface AuthService {
+    /**
+     * Register a new user with email and password.
+     * @returns The created user (not yet email-verified)
+     */
+    register(options: RegisterOptions): Promise<AuthUser>;
+    /**
+     * Authenticate a user and create a session.
+     * @returns Session with access token, refresh token, and user info
+     */
+    login(options: LoginOptions): Promise<AuthSession>;
+    /**
+     * Validate an access token and return the authenticated user.
+     * @param accessToken - JWT access token from login or refresh
+     * @throws If the token is invalid or expired
+     */
+    validate(accessToken: string): Promise<AuthUser>;
+    /**
+     * Refresh a session using a refresh token (single-use).
+     * @param refreshToken - The refresh token from a previous login/refresh
+     * @returns New session with fresh access and refresh tokens
+     */
+    refresh(refreshToken: string): Promise<AuthSession>;
+    /**
+     * Revoke a specific session.
+     */
+    logout(sessionId: string): Promise<void>;
+    /**
+     * Get a user by ID.
+     * @returns The user, or null if not found
+     */
+    getUser(userId: string): Promise<AuthUser | null>;
+    /**
+     * List users with optional filtering and pagination.
+     */
+    listUsers(filter?: UserListFilter): Promise<UserListResponse>;
+    /**
+     * Update a user's email, status, or profile data.
+     */
+    updateUser(userId: string, update: UpdateUserOptions): Promise<AuthUser>;
+    /**
+     * Delete a user and all their sessions.
+     */
+    deleteUser(userId: string): Promise<void>;
+    /**
+     * Create an email verification token.
+     * @returns The verification token (caller decides how to deliver it)
+     */
+    sendVerification(userId: string): Promise<{
+        token: string;
+    }>;
+    /**
+     * Verify an email address using a verification token.
+     */
+    verifyEmail(token: string): Promise<void>;
+    /**
+     * Create a password reset token for an email address.
+     * @returns The reset token (caller decides how to deliver it)
+     */
+    sendPasswordReset(email: string): Promise<{
+        token: string;
+    }>;
+    /**
+     * Reset a password using a reset token.
+     */
+    resetPassword(token: string, newPassword: string): Promise<void>;
+    /**
+     * Change a user's password (requires old password).
+     */
+    changePassword(userId: string, oldPassword: string, newPassword: string): Promise<void>;
+    /**
+     * Get the configured registration fields for this project.
+     */
+    getFieldConfig(): Promise<{
+        fields: AuthField[];
+    }>;
+    /**
+     * Start an OAuth flow by generating an authorization URL.
+     * Redirect the user to the returned URL to begin authentication.
+     *
+     * @param provider - Provider name: "google", "github", "okta", or "custom_oidc"
+     * @param options - Optional configuration
+     * @returns Object with `auth_url` (redirect target) and `state` (for CSRF verification)
+     */
+    getOAuthUrl(provider: string, options?: {
+        redirectUri?: string;
+    }): Promise<{
+        auth_url: string;
+        state: string;
+    }>;
+    /**
+     * Complete an OAuth flow by exchanging the authorization code.
+     * Call this after the provider redirects back with a code and state.
+     *
+     * @param provider - Provider name
+     * @param params - The code and state from the OAuth callback
+     * @returns Either a session (user authenticated) or a link_required result
+     */
+    handleOAuthCallback(provider: string, params: {
+        code: string;
+        state: string;
+    }): Promise<AuthSession | {
+        type: 'LinkRequired';
+        email: string;
+        provider: string;
+        provider_id: string;
+        existing_user_id: string;
+    }>;
+    /**
+     * Middleware helper that validates auth and injects `request.user`.
+     * Returns 401 JSON response if no valid token is found.
+     *
+     * Extracts token from `Authorization: Bearer <token>` header
+     * or `__session` cookie.
+     *
+     * @example
+     * ```typescript
+     * export default {
+     *   fetch: platform.auth.withAuth(async (request) => {
+     *     const data = await platform.db.items.find({ owner: request.user.id });
+     *     return Response.json(data);
+     *   })
+     * };
+     * ```
+     */
+    withAuth<T extends (request: Request & {
+        user: AuthUser;
+    }) => Promise<Response>>(handler: T): (request: Request) => Promise<Response>;
+}
 interface Platform {
     /** Environment containing all available platform services */
     env: PlatformEnv;
@@ -605,6 +877,8 @@ interface Platform {
     media?: MediaService;
     /** Realtime service for pub/sub channels and presence */
     realtime: RealtimeService;
+    /** Auth service for end-user authentication and user management */
+    auth: AuthService;
 }
 
 interface RenEvent {
@@ -721,10 +995,14 @@ declare class RealtimeClient {
     presence(channel: string): {
         /** Join the channel with presence (auto-rejoins on reconnect) */
         join: (userId: string, metadata?: any) => void;
+        /** Update metadata for the current presence (must have joined first) */
+        update: (metadata?: any) => void;
         /** Leave the channel */
         leave: () => void;
         /** Listen for users joining */
         onJoin: (callback: (member: PresenceMember) => void) => Unsubscribe;
+        /** Listen for metadata updates */
+        onUpdate: (callback: (member: PresenceMember) => void) => Unsubscribe;
         /** Listen for users leaving */
         onLeave: (callback: (member: PresenceMember) => void) => Unsubscribe;
     };
@@ -963,4 +1241,4 @@ declare function getPlatform(options?: {
  */
 declare function clearPlatformCache(): void;
 
-export { type Database, type DbFindOptions, type KvListResult, type KvNamespace, 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, RemoteMediaService, RenClient, type RenClientOptions, type RenEvent, type Storage$1 as Storage, type StoragePutStreamSource, type TrackKind, type TrackSource, type VideoResolution, attachTrack, clearPlatformCache, detachTrack, getOrCreateClientId, getPlatform, renFetch, storageDelete, storageUpload };
+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 };

package/dist/index.js

@@ -380,6 +380,108 @@ var RemoteRealtimeService = class {
     return data.channels ?? [];
   }
 };
+var RemoteAuthService = class {
+  constructor(baseUrl, headers) {
+    this.baseUrl = baseUrl;
+    this.headers = headers;
+  }
+  baseUrl;
+  headers;
+  async post(path, body) {
+    const res = await fetch(`${this.baseUrl}/api/platform/auth${path}`, {
+      method: "POST",
+      headers: this.headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Auth error (${res.status}): ${text}`);
+    }
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+  async register(options) {
+    return this.post("/register", options);
+  }
+  async login(options) {
+    return this.post("/login", options);
+  }
+  async validate(accessToken) {
+    return this.post("/validate", { token: accessToken });
+  }
+  async refresh(refreshToken) {
+    return this.post("/refresh", { token: refreshToken });
+  }
+  async logout(sessionId) {
+    await this.post("/logout", { session_id: sessionId });
+  }
+  async getUser(userId) {
+    return this.post("/get-user", { user_id: userId });
+  }
+  async listUsers(filter) {
+    return this.post("/list-users", filter ?? {});
+  }
+  async updateUser(userId, update) {
+    return this.post("/update-user", { user_id: userId, ...update });
+  }
+  async deleteUser(userId) {
+    await this.post("/delete-user", { user_id: userId });
+  }
+  async sendVerification(userId) {
+    return this.post("/send-verification", { user_id: userId });
+  }
+  async verifyEmail(token) {
+    await this.post("/verify-email", { token });
+  }
+  async sendPasswordReset(email) {
+    return this.post("/send-password-reset", { email });
+  }
+  async resetPassword(token, newPassword) {
+    await this.post("/reset-password", { token, new_password: newPassword });
+  }
+  async changePassword(userId, oldPassword, newPassword) {
+    await this.post("/change-password", { user_id: userId, old_password: oldPassword, new_password: newPassword });
+  }
+  async getFieldConfig() {
+    return this.post("/field-config");
+  }
+  async getOAuthUrl(provider, options) {
+    return this.post("/oauth/start", { provider, redirect_uri: options?.redirectUri || `/_auth/callback/${provider}` });
+  }
+  async handleOAuthCallback(provider, params) {
+    return this.post("/oauth/callback", { provider, code: params.code, state: params.state });
+  }
+  withAuth(handler) {
+    const self = this;
+    return async function(request) {
+      let token = null;
+      const authHeader = request.headers.get("Authorization");
+      if (authHeader?.startsWith("Bearer ")) {
+        token = authHeader.slice(7);
+      } else {
+        const cookies = request.headers.get("Cookie") ?? "";
+        const match = cookies.match(/__session=([^;]+)/);
+        if (match) token = match[1];
+      }
+      if (!token) {
+        return new Response(JSON.stringify({ error: "Authentication required" }), {
+          status: 401,
+          headers: { "Content-Type": "application/json" }
+        });
+      }
+      try {
+        const user = await self.validate(token);
+        request.user = user;
+        return handler(request);
+      } catch {
+        return new Response(JSON.stringify({ error: "Invalid or expired token" }), {
+          status: 401,
+          headers: { "Content-Type": "application/json" }
+        });
+      }
+    };
+  }
+};
 function createRemoteClient(baseUrl, tenant) {
   const headers = {
     "Content-Type": "application/json",
@@ -394,6 +496,7 @@ function createRemoteClient(baseUrl, tenant) {
   const storage = new RemoteStorage(baseUrl, headers);
   const media = new RemoteMediaService(baseUrl, headers);
   const realtime = new RemoteRealtimeService(baseUrl, headers);
+  const auth = new RemoteAuthService(baseUrl, headers);
   return {
     env: {
       KV: kvProxy,
@@ -401,7 +504,8 @@ function createRemoteClient(baseUrl, tenant) {
       STORAGE: storage
     },
     media,
-    realtime
+    realtime,
+    auth
   };
 }
 
@@ -677,7 +781,7 @@ var RealtimeClient = class {
         listeners.forEach((cb) => cb(event));
       }
     }
-    if (event.event === "presence:join" || event.event === "presence:leave") {
+    if (event.event === "presence:join" || event.event === "presence:leave" || event.event === "presence:update") {
       const presenceSet = this.presenceListeners.get(event.channel);
       if (presenceSet) {
         const member = {
@@ -687,6 +791,8 @@ var RealtimeClient = class {
         };
         if (event.event === "presence:join") {
           presenceSet.onJoin.forEach((cb) => cb(member));
+        } else if (event.event === "presence:update") {
+          presenceSet.onUpdate.forEach((cb) => cb(member));
         } else {
           presenceSet.onLeave.forEach((cb) => cb(member));
         }
@@ -740,7 +846,8 @@ var RealtimeClient = class {
     if (!this.presenceListeners.has(channel)) {
       this.presenceListeners.set(channel, {
         onJoin: /* @__PURE__ */ new Set(),
-        onLeave: /* @__PURE__ */ new Set()
+        onLeave: /* @__PURE__ */ new Set(),
+        onUpdate: /* @__PURE__ */ new Set()
       });
     }
     const listeners = this.presenceListeners.get(channel);
@@ -755,6 +862,18 @@ var RealtimeClient = class {
           metadata
         });
       },
+      /** Update metadata for the current presence (must have joined first) */
+      update: (metadata) => {
+        const info = this.joinedPresence.get(channel);
+        if (!info) return;
+        info.metadata = metadata;
+        this.sendRaw({
+          action: "presence:update",
+          channel,
+          userId: info.userId,
+          metadata
+        });
+      },
       /** Leave the channel */
       leave: () => {
         this.joinedPresence.delete(channel);
@@ -767,6 +886,13 @@ var RealtimeClient = class {
           listeners.onJoin.delete(callback);
         };
       },
+      /** Listen for metadata updates */
+      onUpdate: (callback) => {
+        listeners.onUpdate.add(callback);
+        return () => {
+          listeners.onUpdate.delete(callback);
+        };
+      },
       /** Listen for users leaving */
       onLeave: (callback) => {
         listeners.onLeave.add(callback);
@@ -1048,7 +1174,7 @@ var MediaRoom = class _MediaRoom {
 };
 
 // src/index.ts
-var cachedPlatform = null;
+var cachedPlatform = void 0;
 function getPlatform(options) {
   if (cachedPlatform) {
     return cachedPlatform;
@@ -1075,7 +1201,7 @@ function getPlatform(options) {
   return cachedPlatform;
 }
 function clearPlatformCache() {
-  cachedPlatform = null;
+  cachedPlatform = void 0;
   if (typeof globalThis !== "undefined") {
     globalThis.__maravilla_platform = void 0;
   }