@mitway/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,432 @@
+import * as _supabase_postgrest_js from '@supabase/postgrest-js';
+
+/**
+ * User shape returned by the MITWAY-BaaS auth endpoints.
+ *
+ * This is a 1:1 inline copy of the `User` zod schema from the BaaS workspace
+ * package `@mitway-baas/shared-schemas` (`src/auth.schema.ts`). It is
+ * inlined here so this SDK has zero internal MITWAY-BaaS workspace
+ * dependencies and can be published to npm standalone.
+ *
+ * If the backend ever changes the User shape, update this type to match.
+ * The fields below should always be a strict subset/superset of what
+ * `POST /api/auth/login` and `POST /api/auth/register` return on the
+ * `user` field of their JSON response.
+ */
+interface User {
+    id: string;
+    email: string;
+    /** Hashed password — usually omitted from API responses but included in the type for shape parity. */
+    password: string | null;
+    is_project_admin: boolean;
+    profile: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    /** ISO 8601 timestamp when the user was banned, or null. */
+    banned_until: string | null;
+    /** ISO 8601 timestamp. */
+    created_at: string;
+    /** ISO 8601 timestamp. */
+    updated_at: string;
+}
+
+/**
+ * MITWAY-BaaS SDK types — only SDK-specific shapes live here.
+ * The `User` shape is inlined in `./lib/user` so this package has zero
+ * MITWAY-BaaS workspace dependencies.
+ */
+
+interface MitwayBaasConfig {
+    /**
+     * Base URL of the MITWAY-BaaS backend (auth, metadata, etc).
+     * @default "http://localhost:7130"
+     */
+    baseUrl?: string;
+    /**
+     * Base URL of the per-cliente PostgREST instance. Used by the database
+     * module. If omitted, calling `client.database.from(...)` will throw at
+     * call time. The PostgREST URL is separate from `baseUrl` because the two
+     * services are deployed as independent Pods in the per-cliente namespace.
+     */
+    postgrestUrl?: string;
+    /**
+     * Anonymous JWT (signed by the tenant's JWT_SECRET, role = "anon").
+     * Used as a fallback Bearer token for unauthenticated requests when no
+     * user session is active.
+     */
+    anonKey?: string;
+    /**
+     * Custom fetch implementation. Useful in Node < 18 or test environments.
+     * Defaults to `globalThis.fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Custom default headers included on every request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Enable debug logging. `true` logs to console; pass a function to receive
+     * log lines instead.
+     */
+    debug?: boolean | ((message: string, ...args: any[]) => void);
+    /**
+     * Per-request timeout in milliseconds. 0 disables the timeout.
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Number of retry attempts on network errors and 5xx responses. Client
+     * errors (4xx) are never retried. 0 disables retries.
+     * @default 3
+     */
+    retryCount?: number;
+    /**
+     * Initial delay before the first retry, in ms. Doubles each attempt with
+     * ±15% jitter.
+     * @default 500
+     */
+    retryDelay?: number;
+    /**
+     * Automatically refresh the access token on 401 INVALID_TOKEN responses
+     * and retry the original request.
+     * @default true
+     */
+    autoRefreshToken?: boolean;
+}
+/**
+ * Active user session in memory. Mirrors what the auth endpoints return.
+ */
+interface AuthSession {
+    user: User;
+    accessToken: string;
+    expiresAt?: Date;
+}
+/**
+ * Minimal payload that auth refresh endpoints emit. The SDK uses this to
+ * refresh the in-memory session.
+ */
+interface AuthRefreshResponse {
+    user: User;
+    accessToken: string;
+    refreshToken?: string;
+    csrfToken?: string;
+}
+/**
+ * The `{ data, error }` envelope used by the MITWAY-BaaS backend on every
+ * response. The SDK unwraps `data` for happy-path returns and converts
+ * `error` into a `MitwayBaasError`.
+ */
+interface ApiError {
+    error: string;
+    message: string;
+    statusCode: number;
+    nextActions?: string;
+}
+declare class MitwayBaasError extends Error {
+    statusCode: number;
+    error: string;
+    nextActions?: string;
+    constructor(message: string, statusCode: number, error: string, nextActions?: string);
+    static fromApiError(apiError: ApiError): MitwayBaasError;
+}
+
+/**
+ * Debug logger for the MITWAY-BaaS SDK.
+ *
+ * Logs HTTP request/response details with automatic redaction of sensitive
+ * headers and body fields. Disabled by default; pass `debug: true` (or a
+ * custom log function) on the SDK config to enable.
+ */
+type LogFunction = (message: string, ...args: any[]) => void;
+declare class Logger {
+    enabled: boolean;
+    private customLog;
+    constructor(debug?: boolean | LogFunction);
+    log(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    logRequest(method: string, url: string, headers?: Record<string, string>, body?: any): void;
+    logResponse(method: string, url: string, status: number, durationMs: number, body?: any): void;
+}
+
+/**
+ * Token Manager for the MITWAY-BaaS SDK.
+ *
+ * In-memory storage for the access token + user. Browser CSRF token lives
+ * in a cookie so the cookie-based refresh flow works across page reloads.
+ */
+
+declare class TokenManager {
+    private accessToken;
+    private user;
+    /** Fired when the access token changes (used by long-lived consumers). */
+    onTokenChange: (() => void) | null;
+    saveSession(session: AuthSession): void;
+    getSession(): AuthSession | null;
+    getAccessToken(): string | null;
+    setAccessToken(token: string): void;
+    getUser(): User | null;
+    setUser(user: User): void;
+    clearSession(): void;
+}
+
+/**
+ * HttpClient with retry, timeout, abort signal composition, and automatic
+ * token refresh on 401 INVALID_TOKEN responses.
+ *
+ * Ported from the InsForge SDK with rebranding plus one route change:
+ * the refresh endpoint is `/api/auth/refresh` (MITWAY-BaaS) instead of
+ * `/api/auth/sessions/current` (InsForge).
+ */
+
+type JsonRequestBody = Record<string, unknown> | unknown[] | null;
+interface RequestOptions extends Omit<RequestInit, 'body'> {
+    params?: Record<string, string>;
+    body?: RequestInit['body'] | JsonRequestBody;
+    /**
+     * Allow retrying non-idempotent requests (POST, PATCH). Off by default to
+     * prevent duplicate writes on transient server errors.
+     */
+    idempotent?: boolean;
+}
+declare class HttpClient {
+    readonly baseUrl: string;
+    readonly fetch: typeof fetch;
+    private defaultHeaders;
+    private anonKey;
+    private userToken;
+    private logger;
+    private autoRefreshToken;
+    private isRefreshing;
+    private refreshPromise;
+    private tokenManager;
+    private refreshToken;
+    private timeout;
+    private retryCount;
+    private retryDelay;
+    constructor(config: MitwayBaasConfig, tokenManager?: TokenManager, logger?: Logger);
+    private buildUrl;
+    private isRetryableStatus;
+    private computeRetryDelay;
+    private handleRequest;
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, body?: any, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    setAuthToken(token: string | null): void;
+    setRefreshToken(token: string | null): void;
+    getHeaders(): Record<string, string>;
+    /**
+     * Refresh the current session by calling the MITWAY-BaaS refresh endpoint.
+     * Note: the route is `/api/auth/refresh` (POST), not the InsForge
+     * `/api/auth/sessions/current` route. Returns the new access token + user.
+     */
+    handleTokenRefresh(): Promise<AuthRefreshResponse>;
+}
+
+/**
+ * Auth module — MITWAY-BaaS specific.
+ *
+ * Targets the routes that the MITWAY-BaaS backend currently exposes:
+ *   POST /api/auth/register   → signUp
+ *   POST /api/auth/login      → signInWithPassword
+ *   POST /api/auth/logout     → signOut
+ *   POST /api/auth/refresh    → refreshSession (also auto-called by HttpClient)
+ *
+ * OAuth, email verification, password reset, and the InsForge-only
+ * profile/sessions admin endpoints are NOT included — the backend does not
+ * implement them yet. When it does, port the corresponding methods from the
+ * upstream InsForge SDK (`InsForge/InsForge-sdk-js/src/modules/auth/auth.ts`).
+ */
+
+interface SignUpRequest {
+    email: string;
+    password: string;
+    name?: string;
+}
+interface SignInRequest {
+    email: string;
+    password: string;
+}
+/**
+ * The shape the backend returns from /register, /login, and /refresh. Mirrors
+ * what the existing backend handlers send: `{ user, accessToken, refreshToken,
+ * csrfToken? }` wrapped in the standard `{ data, error }` envelope. The SDK
+ * unwraps the envelope before reaching this type, so consumers see the raw
+ * shape.
+ */
+interface AuthResponse {
+    user: User;
+    accessToken: string;
+    refreshToken?: string;
+    csrfToken?: string;
+}
+type AuthResult<T> = {
+    data: T | null;
+    error: MitwayBaasError | null;
+};
+declare class Auth {
+    private http;
+    private tokenManager;
+    constructor(http: HttpClient, tokenManager: TokenManager);
+    /**
+     * Persist the session in memory + HttpClient defaults so subsequent
+     * requests carry the new bearer token automatically.
+     */
+    private saveSessionFromResponse;
+    /**
+     * Create a new user account and start a session.
+     *
+     * @example
+     * const { data, error } = await client.auth.signUp({
+     *   email: 'a@b.com',
+     *   password: 'a-strong-password',
+     *   name: 'Alice'
+     * });
+     */
+    signUp(request: SignUpRequest): Promise<AuthResult<AuthResponse>>;
+    /**
+     * Sign in with email + password and start a session.
+     */
+    signInWithPassword(request: SignInRequest): Promise<AuthResult<AuthResponse>>;
+    /**
+     * End the current session. Clears in-memory state even if the backend
+     * call fails (network/offline).
+     */
+    signOut(): Promise<{
+        error: MitwayBaasError | null;
+    }>;
+    /**
+     * Manually refresh the current session. The HttpClient will call this
+     * automatically on 401 INVALID_TOKEN responses; consumers usually do
+     * not need to call it directly.
+     */
+    refreshSession(): Promise<AuthResult<AuthResponse>>;
+    /**
+     * Get the current in-memory session, or null if the user is not signed in.
+     * Synchronous — does not hit the network.
+     */
+    getSession(): AuthSession | null;
+    /**
+     * Get the current in-memory user, or null if not signed in.
+     */
+    getUser(): User | null;
+}
+
+declare class Database {
+    private postgrest;
+    private postgrestUrl;
+    constructor(tokenManager: TokenManager, postgrestUrl: string | undefined, anonKey: string | undefined);
+    private requireClient;
+    /**
+     * Build a PostgREST query against a table.
+     *
+     * @example
+     * const { data, error } = await client.database
+     *   .from('posts')
+     *   .select('*')
+     *   .eq('user_id', userId)
+     *   .order('created_at', { ascending: false })
+     *   .limit(10);
+     *
+     * @example
+     * const { data, error } = await client.database
+     *   .from('posts')
+     *   .insert({ title: 'Hello', content: 'World' })
+     *   .select()
+     *   .single();
+     */
+    from(table: string): _supabase_postgrest_js.PostgrestQueryBuilder<any, any, any, string, unknown>;
+    /**
+     * Call a PostgreSQL stored function (RPC).
+     *
+     * @example
+     * const { data, error } = await client.database
+     *   .rpc('get_user_stats', { user_id: 123 });
+     */
+    rpc(fn: string, args?: Record<string, unknown>, options?: {
+        head?: boolean;
+        get?: boolean;
+        count?: 'exact' | 'planned' | 'estimated';
+    }): _supabase_postgrest_js.PostgrestFilterBuilder<any, any, any, any, string, null, "RPC">;
+    /**
+     * The PostgREST URL the database client is talking to, or undefined if
+     * the database module is not configured.
+     */
+    getUrl(): string | undefined;
+}
+
+/**
+ * MITWAY-BaaS SDK client.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@mitway-baas/sdk';
+ *
+ * const client = createClient({
+ *   baseUrl: 'https://acme.api.dev.nttmitway.com',     // backend (auth)
+ *   postgrestUrl: 'https://acme.db.dev.nttmitway.com', // postgrest (db)
+ *   anonKey: 'eyJhbGciOiJIUzI1NiIs...',                // optional
+ * });
+ *
+ * // Auth
+ * const { data: session, error } = await client.auth.signInWithPassword({
+ *   email: 'a@b.com',
+ *   password: 'pw',
+ * });
+ *
+ * // Database
+ * const { data, error: dbError } = await client.database
+ *   .from('posts')
+ *   .select('*')
+ *   .eq('user_id', session.user.id)
+ *   .order('created_at', { ascending: false });
+ * ```
+ */
+declare class MitwayBaasClient {
+    private http;
+    private tokenManager;
+    readonly auth: Auth;
+    readonly database: Database;
+    constructor(config?: MitwayBaasConfig);
+    /**
+     * Escape hatch for callers that need to make custom requests against the
+     * backend without going through `auth` or `database`.
+     */
+    getHttpClient(): HttpClient;
+}
+
+/**
+ * @mitway-baas/sdk — TypeScript SDK for the MITWAY-BaaS backend.
+ *
+ * Currently ships:
+ *   - auth     (signUp, signInWithPassword, signOut, refreshSession, getSession, getUser)
+ *   - database (PostgREST-backed query builder via @supabase/postgrest-js)
+ *
+ * Not yet included (no backend support):
+ *   - storage
+ *   - functions
+ *   - email
+ *   - ai
+ *   - realtime
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Factory function for creating SDK clients (Supabase-style).
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@mitway-baas/sdk';
+ *
+ * const client = createClient({
+ *   baseUrl: 'https://acme.api.dev.nttmitway.com',
+ *   postgrestUrl: 'https://acme.db.dev.nttmitway.com',
+ * });
+ * ```
+ */
+declare function createClient(config: MitwayBaasConfig): MitwayBaasClient;
+
+export { type ApiError, Auth, type AuthRefreshResponse, type AuthResponse, type AuthResult, type AuthSession, Database, HttpClient, Logger, MitwayBaasClient, type MitwayBaasConfig, MitwayBaasError, type SignInRequest, type SignUpRequest, TokenManager, type User, createClient, MitwayBaasClient as default };