@maravilla-labs/platform 0.3.5 → 0.3.8

package/dist/index.d.ts

@@ -945,6 +945,201 @@ interface UpdateUserOptions {
     /** Profile data to merge */
     profile?: Record<string, any>;
 }
+interface AuthGroup {
+    id: string;
+    name: string;
+    description: string | null;
+    permissions: string[];
+    member_count: number;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateGroupOptions {
+    name: string;
+    description?: string;
+    permissions?: string[];
+}
+interface UpdateGroupOptions {
+    name?: string;
+    description?: string;
+    permissions?: string[];
+}
+interface GroupPermission {
+    resource_name: string;
+    actions: string[];
+}
+interface AuthCircle {
+    id: string;
+    name: string;
+    metadata: Record<string, any> | null;
+    member_count: number;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateCircleOptions {
+    name: string;
+    metadata?: Record<string, any>;
+}
+interface UpdateCircleOptions {
+    name?: string;
+    metadata?: Record<string, any>;
+}
+interface AddCircleMemberOptions {
+    user_id: string;
+    relationship: string;
+    is_primary_contact?: boolean;
+}
+interface CircleMembership {
+    user_id: string;
+    email: string;
+    relationship: string;
+    is_primary_contact: boolean;
+    joined_at: number;
+}
+type ResourceServiceType = 'kv' | 'database' | 'realtime' | 'media' | 'vector' | 'storage' | 'queue' | 'push' | 'workflow' | 'transforms';
+interface Resource {
+    id: string;
+    resource_name: string;
+    title: string;
+    description: string | null;
+    actions: string[];
+    policy: string | null;
+    service_type: ResourceServiceType | null;
+    read_filter: string | null;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateResourceOptions {
+    resource_name: string;
+    title: string;
+    description?: string;
+    actions?: string[];
+    policy?: string;
+    service_type?: ResourceServiceType;
+    read_filter?: string;
+}
+interface UpdateResourceOptions {
+    title?: string;
+    description?: string;
+    actions?: string[];
+    policy?: string;
+    service_type?: ResourceServiceType;
+    read_filter?: string;
+}
+interface RelationType {
+    id: string;
+    relation_name: string;
+    title: string;
+    description: string | null;
+    category: string;
+    icon: string | null;
+    color: string | null;
+    inverse_relation_id: string | null;
+    implies_stewardship: boolean;
+    requires_minor: boolean;
+    bidirectional: boolean;
+    is_system: boolean;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateRelationTypeOptions {
+    relation_name: string;
+    title: string;
+    description?: string;
+    category?: string;
+    icon?: string;
+    color?: string;
+    inverse_relation_id?: string;
+    implies_stewardship?: boolean;
+    requires_minor?: boolean;
+    bidirectional?: boolean;
+    is_system?: boolean;
+}
+interface UpdateRelationTypeOptions {
+    title?: string;
+    description?: string;
+    category?: string;
+    icon?: string;
+    color?: string;
+    inverse_relation_id?: string;
+    implies_stewardship?: boolean;
+    requires_minor?: boolean;
+    bidirectional?: boolean;
+}
+interface AuthConfig {
+    fields: AuthField[];
+    oauth_providers: any[];
+    branding: Record<string, any>;
+    password_policy: Record<string, any>;
+    session_config: Record<string, any>;
+}
+type DelegationMode = 'full' | 'scoped';
+type StewardshipStatus = 'active' | 'suspended' | 'revoked' | 'expired';
+interface ScopedPermission {
+    resource: string;
+    actions: string[];
+}
+interface StewardshipOverride {
+    id: string;
+    steward_id: string;
+    ward_id: string;
+    delegation_mode: DelegationMode;
+    scoped_permissions: ScopedPermission[];
+    valid_from: number | null;
+    valid_until: number | null;
+    status: StewardshipStatus;
+    reason: string | null;
+    source: string;
+    source_circle_id: string | null;
+    source_relation_type_id: string | null;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateStewardshipOverrideOptions {
+    steward_id: string;
+    ward_id: string;
+    delegation_mode?: DelegationMode;
+    scoped_permissions?: ScopedPermission[];
+    valid_from?: number;
+    valid_until?: number;
+    reason?: string;
+}
+interface StewardshipResolution {
+    stewards: StewardshipOverride[];
+    wards: StewardshipOverride[];
+}
+interface ActAsContext {
+    steward_id: string;
+    ward_id: string;
+    delegation_mode: DelegationMode;
+    scoped_permissions: ScopedPermission[];
+    session_token: string;
+    expires_at: number;
+}
+interface StewardshipAuditEntry {
+    id: string;
+    performed_by: string;
+    on_behalf_of: string;
+    action: string;
+    resource: string | null;
+    details: Record<string, any> | null;
+    created_at: number;
+}
+/**
+ * Sub-namespace exposed at `platform.auth.stewardship` mirroring the
+ * runtime's `globalThis.platform.auth.stewardship.*` surface.
+ */
+interface AuthStewardshipApi {
+    resolve(userId: string): Promise<StewardshipResolution>;
+    createOverride(opts: CreateStewardshipOverrideOptions): 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?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<StewardshipAuditEntry[]>;
+}
 /**
  * Auth service for end-user authentication and user management.
  *
@@ -1106,6 +1301,39 @@ interface AuthService {
     withAuth<T extends (request: Request & {
         user: AuthUser;
     }) => Promise<Response>>(handler: T): (request: Request) => Promise<Response>;
+    createGroup(options: CreateGroupOptions): Promise<AuthGroup>;
+    listGroups(): Promise<AuthGroup[]>;
+    getGroup(groupId: string): Promise<AuthGroup | null>;
+    updateGroup(groupId: string, options: UpdateGroupOptions): Promise<AuthGroup>;
+    deleteGroup(groupId: string): Promise<void>;
+    addUserToGroup(userId: string, groupId: string): Promise<void>;
+    removeUserFromGroup(userId: string, groupId: string): Promise<void>;
+    getUserGroups(userId: string): Promise<AuthGroup[]>;
+    getGroupMembers(groupId: string): Promise<AuthUser[]>;
+    getGroupPermissions(groupId: string): Promise<GroupPermission[]>;
+    setGroupPermissions(groupId: string, permissions: GroupPermission[]): Promise<void>;
+    createCircle(options: CreateCircleOptions): Promise<AuthCircle>;
+    listCircles(): Promise<AuthCircle[]>;
+    getCircle(circleId: string): Promise<AuthCircle | null>;
+    updateCircle(circleId: string, options: UpdateCircleOptions): Promise<AuthCircle>;
+    deleteCircle(circleId: string): Promise<void>;
+    addCircleMember(circleId: string, options: AddCircleMemberOptions): Promise<void>;
+    removeCircleMember(circleId: string, userId: string): Promise<void>;
+    getCircleMembers(circleId: string): Promise<CircleMembership[]>;
+    getUserCircles(userId: string): Promise<AuthCircle[]>;
+    createResource(options: CreateResourceOptions): Promise<Resource>;
+    listResources(): Promise<Resource[]>;
+    updateResource(resourceId: string, options: UpdateResourceOptions): Promise<Resource>;
+    deleteResource(resourceId: string): Promise<void>;
+    createRelationType(options: CreateRelationTypeOptions): Promise<RelationType>;
+    listRelationTypes(): Promise<RelationType[]>;
+    updateRelationType(id: string, options: UpdateRelationTypeOptions): Promise<RelationType>;
+    deleteRelationType(id: string): Promise<void>;
+    getProfile(userId: string): Promise<Record<string, any>>;
+    setProfile(userId: string, data: Record<string, any>): Promise<void>;
+    getAuthConfig(): Promise<AuthConfig>;
+    setAuthConfig(config: AuthConfig): Promise<void>;
+    readonly stewardship: AuthStewardshipApi;
     /**
      * Explicitly bind the caller for the remainder of this request.
      * Pass a JWT to validate + bind, or `null` / `""` to clear.
@@ -1652,6 +1880,64 @@ declare class MediaRoom {
     private wireEvents;
 }
 
+/**
+ * Per-request scope for the SDK's remote client. Mirrors the runtime's
+ * `REQUEST_CTX` (a `tokio::task_local!` in Rust) so that
+ * `platform.auth.setCurrentUser(token)`, `getCurrentUser()`, and `can()`
+ * — plus future per-request state like the Layer-2 policy toggle —
+ * have a place to live when the SDK is running outside the runtime
+ * (Vite SSR, Node.js HTTP servers, edge workers that expose Node APIs).
+ *
+ * Implementation: Node's `AsyncLocalStorage`. Tenant code wraps each
+ * inbound request with `runWithRequest(async () => { ... })` so the
+ * store stays scoped to the request's async chain. `setCurrentUser`
+ * / `can` read and write that store; if a tenant forgets to wrap, the
+ * methods either no-op (set) or throw a clear error (get/can).
+ */
+
+interface RequestStore {
+    /** Bound access-token JWT (set by `auth.setCurrentUser`). */
+    token?: string;
+    /** Bound user (cached so `getCurrentUser` doesn't re-validate). */
+    user?: AuthUser;
+    /** Whether Layer-2 policy enforcement is enabled for this request. */
+    policyEnabled: boolean;
+}
+/**
+ * Wrap a function in a fresh request scope. **Rarely needed** — the
+ * Maravilla Vite plugin (`@maravilla-labs/vite-plugin`) auto-opens a
+ * scope around every inbound dev HTTP request, so tenant code
+ * (SvelteKit `hooks.server.ts`, RR/Remix loaders, etc.) reaches
+ * `setCurrentUser/getCurrentUser/can` with a scope already active.
+ *
+ * Reach for `runWithRequest` only when the SDK runs **outside** an
+ * HTTP request: standalone Node scripts, test fixtures, custom
+ * servers that don't go through Vite. Inside an active scope,
+ * `platform.auth.setCurrentUser/getCurrentUser/can` operate on a
+ * per-request store keyed by Node's `AsyncLocalStorage`.
+ *
+ * @example
+ * ```ts
+ * // Test fixture that needs to bind a user before exercising the SDK
+ * await runWithRequest(async () => {
+ *   await getPlatform().auth.setCurrentUser(testToken);
+ *   const result = await getPlatform().env.DB.find('users', {});
+ *   expect(result).toEqual(...);
+ * });
+ * ```
+ */
+declare function runWithRequest<T>(fn: () => Promise<T> | T): Promise<T>;
+/**
+ * Read the current request's store, if any. Returns undefined when
+ * called outside a `runWithRequest` scope. Used by `RemoteAuthService`
+ * and (future) other Remote* services to source per-request state.
+ *
+ * Note: the `als` may not yet be initialised when this is called; in
+ * that case the function returns undefined synchronously. Subsequent
+ * `runWithRequest` calls will populate it.
+ */
+declare function getCurrentRequestStore(): RequestStore | undefined;
+
 /**
  * @fileoverview Maravilla Platform SDK
  *
@@ -1772,4 +2058,4 @@ declare function getPlatform(options?: {
  */
 declare function clearPlatformCache(): void;
 
-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, type WorkflowHandle, type WorkflowRun, type WorkflowRunStatus, type WorkflowStepKind, type WorkflowStepRecord, type Workflows, attachTrack, clearPlatformCache, detachTrack, getPlatform };
+export { type ActAsContext, type AddCircleMemberOptions, type AuthCaller, type AuthCircle, type AuthConfig, type AuthField, type AuthGroup, type AuthService, type AuthSession, type AuthStewardshipApi, type AuthUser, type CircleMembership, type CreateCircleOptions, type CreateGroupOptions, type CreateRelationTypeOptions, type CreateResourceOptions, type CreateStewardshipOverrideOptions, type Database, type DbFindOptions, type DelegationMode, type GroupPermission, 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, type RelationType, RemoteMediaService, type RequestStore, type Resource, type ResourceServiceType, type ScheduleOptions, type ScheduledJob, type ScopedPermission, type SendReport, type StewardshipAuditEntry, type StewardshipOverride, type StewardshipResolution, type StewardshipStatus, type Storage, type StoragePutStreamSource, type StoredPushSubscription, type SubscriptionCounts, type TrackKind, type TrackSource, type UpdateCircleOptions, type UpdateGroupOptions, type UpdateRelationTypeOptions, type UpdateResourceOptions, 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, type WorkflowHandle, type WorkflowRun, type WorkflowRunStatus, type WorkflowStepKind, type WorkflowStepRecord, type Workflows, attachTrack, clearPlatformCache, detachTrack, getCurrentRequestStore, getPlatform, runWithRequest };