@spacelr/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,609 @@
+declare enum FileVisibility {
+    PRIVATE = "private",
+    SHARED = "shared",
+    PUBLIC = "public"
+}
+declare enum GrantType {
+    AUTHORIZATION_CODE = "authorization_code",
+    CLIENT_CREDENTIALS = "client_credentials",
+    REFRESH_TOKEN = "refresh_token"
+}
+declare enum CodeChallengeMethod {
+    PLAIN = "plain",
+    S256 = "S256"
+}
+declare enum SharePermission {
+    READ = "read",
+    WRITE = "write"
+}
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: {
+        message: string;
+        code: string;
+        details?: Record<string, unknown>;
+    };
+}
+
+interface LoginParams {
+    email: string;
+    password: string;
+}
+interface RegisterParams {
+    email: string;
+    password: string;
+    username?: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+}
+interface LoginResponse {
+    user: {
+        id: string;
+        sub: string;
+        email: string;
+        username?: string;
+        name?: string;
+        roles: string[];
+    };
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+}
+interface RegisterResponse {
+    user: {
+        id: string;
+        email: string;
+        username: string;
+        displayName?: string;
+    };
+    access_token: string;
+    refresh_token: string;
+    emailVerificationRequired?: boolean;
+}
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token?: string;
+    scope?: string;
+}
+interface UserInfo {
+    sub: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    preferred_username?: string;
+    picture?: string;
+    updated_at?: number;
+    email?: string;
+    email_verified?: boolean;
+}
+interface UserProfile {
+    id: string;
+    email: string;
+    username?: string;
+    name?: string;
+    roles: string[];
+}
+interface AuthorizationUrlParams {
+    redirectUri: string;
+    responseType?: string;
+    state?: string;
+    scope?: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: CodeChallengeMethod;
+}
+interface ExchangeCodeParams {
+    code: string;
+    redirectUri: string;
+    grantType?: GrantType;
+    clientSecret?: string;
+    codeVerifier?: string;
+}
+interface PKCEChallenge {
+    codeVerifier: string;
+    codeChallenge: string;
+    codeChallengeMethod: CodeChallengeMethod;
+}
+interface OpenIDConfiguration {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    subject_types_supported: string[];
+    id_token_signing_alg_values_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    code_challenge_methods_supported: string[];
+}
+interface JWKSResponse {
+    keys: JWK[];
+}
+interface JWK {
+    kty: string;
+    kid?: string;
+    use?: string;
+    alg?: string;
+    n?: string;
+    e?: string;
+    [key: string]: unknown;
+}
+interface StoredTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+}
+interface TwoFactorResponse {
+    twoFactorRequired: true;
+    twoFactorToken: string;
+}
+interface TwoFactorVerifyParams {
+    token: string;
+    code: string;
+}
+
+interface TokenStorage {
+    getTokens(): Promise<StoredTokens | null>;
+    setTokens(tokens: StoredTokens): Promise<void>;
+    clearTokens(): Promise<void>;
+}
+interface SpacelrClientConfig {
+    /** Project ID for multi-tenant requests */
+    projectId: string;
+    /** OAuth client ID */
+    clientId: string;
+    /** Base URL for the public API gateway (e.g. "http://localhost:3002/api/v1") */
+    apiUrl: string;
+    /** Path for the OAuth authorization endpoint (e.g. "/auth/authorize") */
+    authorizationEndpoint?: string;
+    /** Path for the OAuth token endpoint (e.g. "/auth/token") */
+    tokenEndpoint?: string;
+    /** Path for the OIDC userinfo endpoint (e.g. "/auth/userinfo") */
+    userInfoEndpoint?: string;
+    /** OAuth scopes to request (e.g. ["openid", "profile", "email"]) */
+    scopes?: string[];
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Custom token storage implementation (default: MemoryTokenStorage) */
+    tokenStorage?: TokenStorage;
+    /** Buffer in seconds before token expiry to trigger auto-refresh (default: 60) */
+    refreshBufferSeconds?: number;
+}
+
+interface FileInfo {
+    id: string;
+    filename: string;
+    originalFilename: string;
+    mimeType: string;
+    sizeBytes: number;
+    visibility: FileVisibility;
+    ownerId: string;
+    projectId: string;
+    description?: string;
+    createdAt: string;
+    updatedAt: string;
+    shareCount?: number;
+}
+interface FileListResponse {
+    files: FileInfo[];
+    total: number;
+}
+interface ListFilesParams {
+    limit?: number;
+    offset?: number;
+}
+interface InitMultipartUploadParams {
+    filename: string;
+    mimeType: string;
+    totalSizeBytes: number;
+    visibility?: FileVisibility;
+    description?: string;
+}
+interface InitMultipartUploadResponse {
+    fileId: string;
+    uploadId: string;
+    partSize: number;
+    totalParts: number;
+}
+interface PartEtag {
+    partNumber: number;
+    etag: string;
+}
+interface ShareFileParams {
+    userIds: string[];
+    permission?: SharePermission;
+}
+interface UnshareFileParams {
+    userIds: string[];
+}
+interface QuotaInfo {
+    userId: string;
+    projectId: string;
+    quotaBytes: number;
+    usedBytes: number;
+    availableBytes: number;
+    usagePercentage: number;
+    fileCount: number;
+}
+interface DownloadUrlResponse {
+    downloadUrl: string;
+    expiresIn: number;
+}
+interface UploadFileParams {
+    filename: string;
+    mimeType: string;
+    visibility?: FileVisibility;
+    description?: string;
+}
+interface UploadLargeFileParams extends UploadFileParams {
+    /** Concurrent part uploads (default: 3) */
+    concurrency?: number;
+}
+interface UploadProgress {
+    loaded: number;
+    total: number;
+    percentage: number;
+}
+
+type RefreshCallback = (refreshToken: string) => Promise<StoredTokens>;
+declare class TokenManager {
+    private storage;
+    private refreshBufferSeconds;
+    private refreshCallback;
+    private refreshPromise;
+    constructor(storage?: TokenStorage, refreshBufferSeconds?: number);
+    setRefreshCallback(callback: RefreshCallback): void;
+    getAccessToken(): Promise<string | null>;
+    setTokens(tokens: StoredTokens): Promise<void>;
+    clearTokens(): Promise<void>;
+    getStoredTokens(): Promise<StoredTokens | null>;
+    private isTokenExpired;
+    private shouldRefresh;
+    private tryRefresh;
+    private executeRefresh;
+}
+
+interface HttpRequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    authenticated?: boolean;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | undefined>;
+    /** Send cookies cross-origin (credentials: 'include'). Defaults to true for /auth/ paths. */
+    withCredentials?: boolean;
+}
+declare class HttpClient {
+    private config;
+    private tokenManager;
+    constructor(config: SpacelrClientConfig, tokenManager: TokenManager);
+    request<T>(options: HttpRequestOptions): Promise<T>;
+    uploadForm<T>(path: string, formData: FormData, onProgress?: (event: {
+        loaded: number;
+        total: number;
+    }) => void): Promise<T>;
+    private uploadFormWithProgress;
+    private buildUrl;
+    private buildHeaders;
+    private buildFormHeaders;
+    private parseResponse;
+    private throwHttpError;
+    private extractData;
+}
+
+declare class MemoryTokenStorage implements TokenStorage {
+    private tokens;
+    getTokens(): Promise<StoredTokens | null>;
+    setTokens(tokens: StoredTokens): Promise<void>;
+    clearTokens(): Promise<void>;
+}
+declare class BrowserTokenStorage implements TokenStorage {
+    private readonly storageKey;
+    constructor(storageKey?: string);
+    getTokens(): Promise<StoredTokens | null>;
+    setTokens(tokens: StoredTokens): Promise<void>;
+    clearTokens(): Promise<void>;
+}
+
+declare function generatePKCEChallenge(): Promise<PKCEChallenge>;
+
+declare class SpacelrError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, statusCode?: number, details?: Record<string, unknown>);
+}
+declare class SpacelrAuthError extends SpacelrError {
+    constructor(message: string, statusCode?: number, details?: Record<string, unknown>);
+}
+declare class SpacelrNetworkError extends SpacelrError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class SpacelrTimeoutError extends SpacelrError {
+    constructor(timeoutMs: number);
+}
+declare class SpacelrTwoFactorRequiredError extends SpacelrError {
+    readonly twoFactorToken: string;
+    constructor(twoFactorToken: string, details?: Record<string, unknown>);
+}
+declare class SpacelrEmailVerificationRequiredError extends SpacelrError {
+    readonly emailSent: boolean;
+    constructor(emailSent: boolean, details?: Record<string, unknown>);
+}
+
+interface DatabaseChangeEvent {
+    type: 'insert' | 'update' | 'delete';
+    projectId: string;
+    collectionName: string;
+    documentId: string;
+    document?: Record<string, unknown>;
+    timestamp: number;
+}
+interface RealtimeConfig {
+    baseUrl: string;
+    getToken: () => Promise<string | null>;
+}
+declare class RealtimeClient {
+    private socket;
+    private config;
+    private subscriptions;
+    private connecting;
+    private roomWhereMap;
+    constructor(config: RealtimeConfig);
+    subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error) => void, where?: Record<string, string | number | boolean>): Promise<() => void>;
+    disconnect(): void;
+    private buildRoomKey;
+    private ensureConnected;
+    private connect;
+    private eventMatchesRoom;
+    private resubscribeAll;
+}
+
+declare class AuthModule {
+    private http;
+    private tokenManager;
+    private config;
+    constructor(http: HttpClient, tokenManager: TokenManager, config: SpacelrClientConfig);
+    login(params: LoginParams): Promise<LoginResponse>;
+    register(params: RegisterParams): Promise<RegisterResponse>;
+    refresh(refreshToken: string): Promise<TokenResponse>;
+    getProfile(): Promise<UserProfile>;
+    logout(): Promise<void>;
+    verifyEmail(token: string): Promise<{
+        message: string;
+    }>;
+    resendVerification(email: string): Promise<{
+        message: string;
+    }>;
+    getUserInfo(): Promise<UserInfo>;
+    getAuthorizationUrl(params: AuthorizationUrlParams): string;
+    exchangeCode(params: ExchangeCodeParams): Promise<TokenResponse>;
+    generatePKCE(): Promise<PKCEChallenge>;
+    getOpenIDConfiguration(): Promise<OpenIDConfiguration>;
+    getJWKS(): Promise<JWKSResponse>;
+    /**
+     * Request a password reset email.
+     * Always returns a generic message regardless of whether the email exists.
+     */
+    requestPasswordReset(email: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Reset password using a token received via email.
+     */
+    resetPassword(token: string, password: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Exchange a one-time verification code for tokens.
+     * Use this after email verification redirects the user with a ?loginCode= parameter.
+     */
+    exchangeVerificationCode(code: string): Promise<LoginResponse>;
+    /**
+     * Resend a two-factor authentication code email.
+     * Call this when the user hasn't received the code or it expired.
+     */
+    resendTwoFactorCode(token: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Verify a two-factor authentication code.
+     * Call this after catching SpacelrTwoFactorRequiredError from login().
+     */
+    verifyTwoFactor(params: TwoFactorVerifyParams): Promise<LoginResponse>;
+    private storeTokensFromLogin;
+    private storeTokensFromRegister;
+}
+
+declare class StorageModule {
+    private http;
+    private tokenManager;
+    private config;
+    constructor(http: HttpClient, tokenManager: TokenManager, config: SpacelrClientConfig);
+    /**
+     * Upload a file through the gateway (no direct MinIO access).
+     * Accepts a Blob/File (browser) or ArrayBuffer/Uint8Array (Node).
+     */
+    uploadFile(file: Blob | ArrayBuffer | Uint8Array, params: UploadFileParams, onProgress?: (progress: UploadProgress) => void): Promise<FileInfo>;
+    /**
+     * Upload a large file using multipart upload through the gateway.
+     * Splits into parts, uploads concurrently, and completes.
+     */
+    uploadLargeFile(file: Blob | ArrayBuffer | Uint8Array, params: UploadLargeFileParams, onProgress?: (progress: UploadProgress) => void): Promise<FileInfo>;
+    initMultipartUpload(params: InitMultipartUploadParams): Promise<InitMultipartUploadResponse>;
+    completeMultipartUpload(fileId: string, parts: PartEtag[]): Promise<FileInfo>;
+    abortMultipartUpload(fileId: string): Promise<void>;
+    listFiles(params?: ListFilesParams): Promise<FileListResponse>;
+    listSharedFiles(params?: ListFilesParams): Promise<FileListResponse>;
+    getFileInfo(fileId: string): Promise<FileInfo>;
+    downloadFile(fileId: string): Promise<Blob>;
+    getDownloadUrl(fileId: string): Promise<DownloadUrlResponse>;
+    deleteFile(fileId: string): Promise<void>;
+    shareFile(fileId: string, params: ShareFileParams): Promise<void>;
+    unshareFile(fileId: string, params: UnshareFileParams): Promise<void>;
+    updateVisibility(fileId: string, visibility: FileVisibility): Promise<FileInfo>;
+    getQuota(): Promise<QuotaInfo>;
+    getPublicFileUrl(fileId: string, projectId?: string): Promise<string>;
+}
+
+interface PopulateOption {
+    field: string;
+    collection: string;
+    foreignField?: string;
+}
+interface FindResult<T = Record<string, unknown>> {
+    documents: (T & {
+        _id: string;
+    })[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface InsertResult {
+    insertedCount: number;
+    insertedIds: string[];
+}
+interface UpdateResult {
+    matchedCount: number;
+    modifiedCount: number;
+}
+interface DeleteResult {
+    deletedCount: number;
+}
+interface FindByIdOptions {
+    populate?: PopulateOption[];
+}
+interface SubscribeHandlers<T = Record<string, unknown>> {
+    where?: Record<string, string | number | boolean>;
+    onInsert?: (doc: T & {
+        _id: string;
+    }) => void;
+    onUpdate?: (doc: T & {
+        _id: string;
+    }) => void;
+    onDelete?: (documentId: string) => void;
+    onError?: (error: Error) => void;
+}
+declare class QueryBuilder<T = Record<string, unknown>> {
+    private http;
+    private basePath;
+    private _filter?;
+    private _sort?;
+    private _limit?;
+    private _offset?;
+    private _fields?;
+    private _populate;
+    constructor(http: HttpClient, basePath: string, filter?: Record<string, unknown>);
+    sort(sort: Record<string, 1 | -1>): QueryBuilder<T>;
+    limit(limit: number): QueryBuilder<T>;
+    offset(offset: number): QueryBuilder<T>;
+    select(fields: string[]): QueryBuilder<T>;
+    populate(field: string, collection: string, foreignField?: string): QueryBuilder<T>;
+    execute(): Promise<FindResult<T>>;
+}
+declare class CollectionRef<T = Record<string, unknown>> {
+    private http;
+    private realtime;
+    private projectId;
+    private basePath;
+    private collectionName;
+    constructor(http: HttpClient, realtime: RealtimeClient | null, projectId: string, collectionName: string);
+    insert(document: Partial<T> & {
+        _id?: string;
+    }): Promise<InsertResult>;
+    insertMany(documents: (Partial<T> & {
+        _id?: string;
+    })[]): Promise<InsertResult>;
+    find(filter?: Record<string, unknown>): QueryBuilder<T>;
+    findById(id: string, options?: FindByIdOptions): Promise<T & {
+        _id: string;
+    }>;
+    update(id: string, update: Partial<T>): Promise<UpdateResult>;
+    delete(id: string): Promise<DeleteResult>;
+    count(filter?: Record<string, unknown>): Promise<number>;
+    subscribe(handlers: SubscribeHandlers<T>): () => void;
+}
+declare class DatabaseModule {
+    private http;
+    private realtime;
+    private projectId;
+    constructor(http: HttpClient, projectId: string, realtime?: RealtimeClient);
+    collection<T = Record<string, unknown>>(name: string): CollectionRef<T>;
+}
+
+interface PushSubscriptionInfo {
+    id: string;
+    platform: 'web' | 'android' | 'ios';
+    endpoint?: string;
+    deviceToken?: string;
+    deviceId?: string;
+    deviceName?: string;
+    userAgent?: string;
+    isActive: boolean;
+    lastUsedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface VapidKeyResponse {
+    publicKey: string;
+}
+declare class NotificationsModule {
+    private http;
+    private customDeviceId;
+    private customDeviceName;
+    constructor(http: HttpClient);
+    /** Set a custom device ID (e.g. from Capacitor Preferences for persistence beyond localStorage) */
+    setDeviceId(id: string): void;
+    /** Set a custom device name (e.g. "iOS App", "macOS - Chrome") */
+    setDeviceName(name: string): void;
+    /** Get or generate a stable device identifier. Custom ID takes priority over localStorage. */
+    private getDeviceId;
+    /** Get device name: custom name > auto-detected from user agent > undefined */
+    private getDeviceName;
+    /** Auto-detect a short device label from navigator.userAgent (e.g. "macOS - Chrome") */
+    private detectDeviceName;
+    /** Get the VAPID public key for Web Push setup */
+    getVapidPublicKey(): Promise<VapidKeyResponse>;
+    /** Register a push subscription (web, android, or ios) */
+    subscribe(subscription: {
+        platform: 'web' | 'android' | 'ios';
+        endpoint?: string;
+        keys?: {
+            p256dh: string;
+            auth: string;
+        };
+        deviceToken?: string;
+    }, deviceName?: string): Promise<PushSubscriptionInfo>;
+    /** Unregister a push subscription */
+    unsubscribe(platform: 'web' | 'android' | 'ios', identifier: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** Get all subscriptions for the current user */
+    getSubscriptions(): Promise<PushSubscriptionInfo[]>;
+    /**
+     * Helper: Register browser Web Push subscription.
+     * Requests notification permission, subscribes via Push API,
+     * and registers the subscription with the server.
+     */
+    registerBrowserPush(serviceWorkerRegistration: ServiceWorkerRegistration, deviceName?: string): Promise<PushSubscriptionInfo>;
+    /**
+     * Helper: Register a mobile device push token (FCM or APNs).
+     */
+    registerDevicePush(deviceToken: string, platform: 'android' | 'ios', deviceName?: string): Promise<PushSubscriptionInfo>;
+    private urlBase64ToUint8Array;
+}
+
+interface SpacelrClient {
+    readonly auth: AuthModule;
+    readonly storage: StorageModule;
+    readonly db: DatabaseModule;
+    readonly notifications: NotificationsModule;
+    /** Disconnect realtime WebSocket (if connected) */
+    disconnect(): void;
+}
+declare function createClient(config: SpacelrClientConfig): SpacelrClient;
+
+export { type ApiResponse, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type SubscribeHandlers, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, type VapidKeyResponse, createClient, generatePKCEChallenge };