@genation/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,823 @@
+/**
+ * Authentication-related errors
+ */
+export declare class AuthError extends GenationError {
+    constructor(message: string, code: string, cause?: unknown);
+    static invalidGrant(message?: string): AuthError;
+    static accessDenied(message?: string): AuthError;
+    static expiredToken(message?: string): AuthError;
+    static invalidState(message?: string): AuthError;
+    static pkceVerificationFailed(message?: string): AuthError;
+}
+
+/**
+ * Authentication state change event types
+ *
+ * Events are fired in the following scenarios:
+ * - `INITIAL_SESSION`: Fired once when `onAuthStateChange` is first called.
+ *   Session may or may not exist depending on previous auth state.
+ * - `SIGNED_IN`: Fired when user successfully completes OAuth flow via `handleCallback()`.
+ * - `SIGNED_OUT`: Fired when user signs out via `signOut()` or session expires.
+ * - `TOKEN_REFRESHED`: Fired when access token is automatically refreshed.
+ *
+ * @example
+ * ```typescript
+ * client.onAuthStateChange((event, session) => {
+ *   switch (event) {
+ *     case 'INITIAL_SESSION':
+ *       // Check if user was previously logged in
+ *       break;
+ *     case 'SIGNED_IN':
+ *       // Redirect to dashboard
+ *       break;
+ *     case 'SIGNED_OUT':
+ *       // Clear app state, redirect to home
+ *       break;
+ *     case 'TOKEN_REFRESHED':
+ *       // Update cached token if needed
+ *       break;
+ *   }
+ * });
+ * ```
+ */
+export declare type AuthEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED";
+
+/**
+ * Callback function signature for auth state change events
+ *
+ * @param event - Type of auth event that occurred
+ * @param session - Current session if authenticated, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const callback: AuthStateChangeCallback = (event, session) => {
+ *   console.log(`Auth event: ${event}`, session?.user?.email);
+ * };
+ * ```
+ */
+export declare type AuthStateChangeCallback = (event: AuthEvent, session: Session | null) => void;
+
+/**
+ * Configuration-related errors
+ */
+export declare class ConfigError extends GenationError {
+    constructor(message: string);
+    static missingField(field: string): ConfigError;
+}
+
+/**
+ * Create a new Genation client instance
+ *
+ * Factory function for creating SDK client with configuration.
+ *
+ * @param config - Client configuration options
+ * @returns Configured GenationClient instance
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'genation';
+ *
+ * const client = createClient({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'http://localhost:3000/callback',
+ *   // Optional
+ *   scopes: ['openid', 'profile', 'email'],
+ *   storage: 'localStorage',
+ * });
+ * ```
+ */
+export declare function createClient(config: GenationConfig): GenationClient;
+
+/**
+ * Create a storage instance based on type
+ *
+ * @param type - Storage type to create
+ * @returns Storage implementation
+ *
+ * @example
+ * ```typescript
+ * const storage = createStorage('localStorage');
+ * await storage.set('key', 'value');
+ * ```
+ */
+export declare function createStorage(type?: StorageType): TokenStorage;
+
+/**
+ * Main Genation SDK client
+ *
+ * OAuth 2.1 authentication client for Genation platform.
+ * Supports PKCE flow and automatic token refresh.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'genation';
+ *
+ * const client = createClient({
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'http://localhost:3000/callback'
+ * });
+ *
+ * // Listen to auth state changes
+ * const { subscription } = client.onAuthStateChange((event, session) => {
+ *   if (event === 'SIGNED_IN') {
+ *     console.log('User signed in:', session?.user);
+ *   }
+ * });
+ *
+ * // Start login flow
+ * window.location.href = await client.signIn();
+ * ```
+ */
+export declare class GenationClient {
+    private oauth;
+    private tokenManager;
+    private http;
+    private httpServer;
+    private listeners;
+    private initialized;
+    constructor(config: GenationConfig);
+    private validateConfig;
+    /**
+     * Emit auth state change event to all listeners
+     */
+    private emitAuthStateChange;
+    /**
+     * Listen to authentication state changes
+     *
+     * Register a callback that fires when:
+     * - `INITIAL_SESSION`: On first subscription, with current session state
+     * - `SIGNED_IN`: User successfully authenticated
+     * - `SIGNED_OUT`: User logged out or session expired
+     * - `TOKEN_REFRESHED`: Access token was automatically refreshed
+     *
+     * @param callback - Function called on each auth state change
+     * @returns Object containing subscription with `unsubscribe()` method
+     *
+     * @example
+     * ```typescript
+     * const { subscription } = client.onAuthStateChange((event, session) => {
+     *   console.log('Auth event:', event);
+     *
+     *   if (event === 'INITIAL_SESSION') {
+     *     // Check if user was previously logged in
+     *     if (session) {
+     *       console.log('Welcome back!', session.user);
+     *     }
+     *   } else if (event === 'SIGNED_IN') {
+     *     // User just signed in
+     *     console.log('Signed in:', session?.user);
+     *   } else if (event === 'SIGNED_OUT') {
+     *     // Clear app state, redirect to login
+     *     console.log('Signed out');
+     *   }
+     * });
+     *
+     * // Cleanup when component unmounts
+     * subscription.unsubscribe();
+     * ```
+     */
+    onAuthStateChange(callback: AuthStateChangeCallback): {
+        subscription: Subscription;
+    };
+    /**
+     * Start OAuth sign-in flow
+     *
+     * Generates authorization URL with PKCE challenge.
+     * Redirect user to this URL to start authentication.
+     *
+     * @returns Authorization URL to redirect user to
+     *
+     * @example
+     * ```typescript
+     * async function handleLogin() {
+     *   const url = await client.signIn();
+     *   window.location.href = url;
+     * }
+     * ```
+     */
+    signIn(): Promise<string>;
+    /**
+     * Handle OAuth callback after user authentication
+     *
+     * Call this on your redirect URI page to exchange
+     * the authorization code for access tokens.
+     * Triggers `SIGNED_IN` event on success.
+     *
+     * @param code - Authorization code from URL query params
+     * @param state - State parameter for CSRF validation
+     * @returns Token set with access and refresh tokens
+     * @throws {AuthError} If state mismatch or code exchange fails
+     *
+     * @example
+     * ```typescript
+     * // On your /callback page
+     * async function handleCallback() {
+     *   const params = new URLSearchParams(window.location.search);
+     *   const code = params.get('code');
+     *   const state = params.get('state');
+     *
+     *   if (code && state) {
+     *     await client.handleCallback(code, state);
+     *     // onAuthStateChange will fire with SIGNED_IN event
+     *   }
+     * }
+     * ```
+     */
+    handleCallback(code: string, state: string): Promise<TokenSet>;
+    /**
+     * Sign out and revoke tokens
+     *
+     * Clears local session and revokes tokens on server.
+     * Triggers `SIGNED_OUT` event for all listeners.
+     *
+     * @example
+     * ```typescript
+     * async function handleLogout() {
+     *   await client.signOut();
+     *   // onAuthStateChange will fire with SIGNED_OUT event
+     * }
+     * ```
+     */
+    signOut(): Promise<void>;
+    /**
+     * Get current session
+     *
+     * Returns session with access token and user info.
+     * Automatically refreshes token if expired.
+     *
+     * @returns Current session or null if not authenticated
+     *
+     * @example
+     * ```typescript
+     * const session = await client.getSession();
+     * if (session) {
+     *   console.log('Logged in as:', session.user?.email);
+     *
+     *   // Use access token for API calls
+     *   fetch('/api/data', {
+     *     headers: { Authorization: `Bearer ${session.accessToken}` }
+     *   });
+     * }
+     * ```
+     */
+    getSession(): Promise<Session | null>;
+    /**
+     * Get licenses
+     * @param accessToken - The access token to use for the request
+     * @param options - The options for the request
+     * @param options.expiresAfter - Query licenses that are expired after the given date, default set to today to get all valid licenses (unexpired licenses)
+     * @returns The licenses
+     */
+    getLicenses(options?: {
+        expiresAfter?: Date;
+    }): Promise<License[] | null>;
+    /**
+     * Fetch user info from auth server
+     */
+    private fetchUser;
+}
+
+/**
+ * @fileoverview SDK configuration types for Genation SDK
+ * @module types/config
+ */
+/**
+ * Genation SDK configuration options
+ *
+ * Required configuration for initializing the SDK client.
+ * Obtain `clientId` and `clientSecret` from the Genation developer portal.
+ *
+ * @example
+ * ```typescript
+ * import { createClient, GenationConfig } from 'genation';
+ *
+ * const config: GenationConfig = {
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'http://localhost:3000/callback',
+ *   scopes: ['openid', 'profile', 'email'],
+ *   storage: 'localStorage',
+ * };
+ *
+ * const client = createClient(config);
+ * ```
+ */
+export declare interface GenationConfig {
+    /**
+     * OAuth client ID from Genation developer portal
+     * Unique identifier for your application
+     * @required
+     */
+    clientId: string;
+    /**
+     * OAuth client secret from Genation developer portal
+     *
+     * **Security note:**
+     * - Frontend apps: PKCE provides protection, secret exposure is acceptable
+     * - Backend apps: Keep secret secure on server-side only
+     *
+     * @required
+     */
+    clientSecret: string;
+    /**
+     * Registered redirect URI for OAuth callback
+     *
+     * Must exactly match a URI registered in developer portal.
+     * User will be redirected here after authentication.
+     *
+     * @required
+     * @example "http://localhost:3000/callback"
+     * @example "https://myapp.com/auth/callback"
+     */
+    redirectUri: string;
+    /**
+     * OAuth scopes to request during authorization
+     *
+     * Controls what user data your app can access.
+     *
+     * @default undefined (Server handles defaults)
+     * @example ['openid', 'profile', 'email']
+     */
+    scopes?: string[];
+    /**
+     * Custom auth server URL
+     *
+     * Override if using a custom Genation deployment.
+     *
+     * @default "https://mnnoheowoowbtpuoguul.supabase.co/auth/v1"
+     */
+    authUrl?: string;
+    /**
+     * Token storage strategy
+     *
+     * - `'localStorage'`: Persist across browser sessions (default)
+     * - `'sessionStorage'`: Clear when tab closes
+     * - `'memory'`: Clear on page refresh (most secure, least convenient)
+     *
+     * @default 'localStorage'
+     */
+    storage?: StorageType;
+}
+
+/**
+ * Base error class for Genation SDK
+ */
+export declare class GenationError extends Error {
+    code: string;
+    cause?: unknown;
+    constructor(message: string, code: string, cause?: unknown);
+}
+
+/**
+ * Represents an individual license issued for a user or entity.
+ * A license grants access to an application under specific terms, durations, and plans.
+ */
+declare interface License {
+    /**
+     * Unique identifier for the license.
+     * Typically a UUID string.
+     * Example: 'b23f680b-968d-4db3-a1ef-1870eaa8b17e'
+     */
+    id: string;
+    /**
+     * Alphanumeric code or token that represents the ownership or grant of this license.
+     * May be used for redeeming, activating, or looking up the license.
+     * Example: 'ACME-56T9-PX24-2024'
+     */
+    code: string;
+    /**
+     * The foreign key referencing the license plan this license was issued under.
+     * This ties the license to a specific set of plan attributes/entitlements.
+     * Example: '15f24aa1-83e2-4f6c-af22-b2e159d56f98'
+     */
+    app_plan_id: string;
+    /**
+     * The total duration (in calendar days) for which the license is valid after being redeemed or activated.
+     * Example: 30 (for a one-month license), 365 (for annual licenses)
+     */
+    duration_days: number;
+    /**
+     * Optionally, the UUID of a plan term or subscription cycle associated with the license, if applicable.
+     * Can be null if the license does not have distinct terms.
+     * Example: 'random<uuid>', or null for perpetual/server-issued licenses.
+     */
+    plan_term_id: string | null;
+    /**
+     * The user UUID (or organization ID) of the purchaser who paid for or obtained the license.
+     * This identifies the buying entity. May be a UUID string.
+     * Example: 'uuid'
+     */
+    purchaser_id: string;
+    /**
+     * The user UUID of the account that redeemed or is assigned this license.
+     * For team or transferred licenses, this may differ from purchaser_id.
+     * Example: 'uuid'
+     */
+    redeemed_by: string;
+    /**
+     * The ISO 8601 timestamp when the license was purchased, invoiced, or issued (by admin/tool).
+     * Format: 'YYYY-MM-DDTHH:mm:ss.sssZ'
+     * Example: '2024-06-05T14:00:13.001Z'
+     */
+    purchased_at: string;
+    /**
+     * The ISO 8601 timestamp when the license was redeemed or activated by a user for use.
+     * May be equal to purchased_at for immediate use, or later if redeemed by a team member.
+     * Format: 'YYYY-MM-DDTHH:mm:ss.sssZ'
+     * Example: '2024-06-05T16:20:27.330Z'
+     */
+    redeemed_at: string;
+    /**
+     * Optional note from the purchaser (attached to the license at order time).
+     * Could contain recipient info, business notes, or a purpose for purchase.
+     * Example: 'For Emily - Happy birthday!', 'Procured by IT Services, invoice #2024-1091'
+     */
+    purchaser_note: string;
+    /**
+     * The ISO 8601 timestamp for license expiration or end of entitlement.
+     * After this date, the license is considered expired and may not grant access.
+     * Format: 'YYYY-MM-DDTHH:mm:ss.sssZ'
+     * Example: '2025-06-05T16:20:27.000Z'
+     */
+    expires_at: string;
+    /**
+     * String representing the license status in the system.
+     * Common examples: 'available', 'active', 'expired'
+     * Used to control access and display state in user/admin portals.
+     */
+    status: LicenseStatus;
+    /**
+     * The license plan details that define the attributes/entitlements for this license.
+     * Fully inlines the associated LicensePlan object.
+     */
+    plan: LicensePlan;
+}
+
+/**
+ * Represents a license plan, which defines the properties of a license tier or offering for an application.
+ */
+declare interface LicensePlan {
+    /**
+     * Unique identifier for the license plan.
+     * Typically a UUID string assigned by the backend.
+     * Example: 'f265b8c0-0ef1-4cc0-b37b-92dded82d49a'
+     */
+    id: string;
+    /**
+     * The unique ID of the application this plan belongs to.
+     * Maps to the application entity in the system.
+     * Example: 'app_003cd5870d'
+     */
+    app_id: string;
+    /**
+     * The public (human-readable or machine-friendly) code for the plan.
+     * Used for referencing the plan in APIs, admin panels, or order forms.
+     * Example: 'PRO', 'TEAM_2023', 'ENTERPRISE'
+     */
+    code: string;
+    /**
+     * The display name of the license plan.
+     * Used for showing to end users in UIs.
+     * Example: 'Pro Plan', 'Enterprise Annual Subscription'
+     */
+    name: string;
+    /**
+     * The ISO 8601 timestamp when this plan was created in the system.
+     * Format: 'YYYY-MM-DDTHH:mm:ss.sssZ'
+     * Example: '2024-06-05T12:34:56.789Z'
+     */
+    created_at: string;
+}
+
+/**
+ * The status of a license.
+ * Example: 'available', 'active', 'expired'
+ * available: the license is available to be redeemed
+ * active: the license is redeemed and can know as valid license
+ * expired: the license has expired and can no longer be used
+ */
+declare type LicenseStatus = "available" | "active" | "expired";
+
+/**
+ * Browser localStorage implementation
+ * Tokens persist across browser sessions
+ */
+export declare class LocalStorage implements TokenStorage {
+    private prefix;
+    constructor(prefix?: string);
+    private getKey;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * In-memory storage implementation
+ * Tokens are lost when page refreshes
+ */
+export declare class MemoryStorage implements TokenStorage {
+    private store;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Network-related errors
+ */
+export declare class NetworkError extends GenationError {
+    status?: number;
+    constructor(message: string, status?: number, cause?: unknown);
+    static fromResponse(response: Response): NetworkError;
+}
+
+/**
+ * PKCE (Proof Key for Code Exchange) challenge pair
+ *
+ * Generated internally by SDK for OAuth 2.1 authorization code flow.
+ * The verifier is stored and used during token exchange, while the
+ * challenge is sent with the authorization request.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7636 | RFC 7636 - PKCE}
+ */
+export declare interface PKCEChallenge {
+    /**
+     * High-entropy cryptographic random string (43-128 chars)
+     * Stored locally and sent during token exchange
+     */
+    codeVerifier: string;
+    /**
+     * Base64URL-encoded SHA-256 hash of the code verifier
+     * Sent with authorization request
+     */
+    codeChallenge: string;
+    /**
+     * Challenge derivation method, always 'S256' for OAuth 2.1
+     * Plain method is deprecated and not supported
+     */
+    codeChallengeMethod: "S256";
+}
+
+/**
+ * Active user session containing tokens and user information
+ *
+ * Returned by `getSession()` and passed to `onAuthStateChange` callback.
+ * Contains everything needed to make authenticated API requests.
+ *
+ * @example
+ * ```typescript
+ * const session = await client.getSession();
+ * if (session) {
+ *   // Use access token for API calls
+ *   fetch('/api/data', {
+ *     headers: { Authorization: `Bearer ${session.accessToken}` }
+ *   });
+ *
+ *   // Check token expiration
+ *   if (Date.now() > session.expiresAt) {
+ *     console.log('Token expired');
+ *   }
+ * }
+ * ```
+ */
+export declare interface Session {
+    /**
+     * JWT access token for authenticating API requests
+     * Include in Authorization header: `Bearer ${accessToken}`
+     */
+    accessToken: string;
+    /**
+     * Refresh token for obtaining new access tokens
+     * Managed internally by SDK, typically not needed directly
+     */
+    refreshToken?: string;
+    /**
+     * Access token lifetime in seconds from issue time
+     * @example 3600 // 1 hour
+     */
+    expiresIn: number;
+    /**
+     * Unix timestamp (ms) when the access token expires
+     * Use to check if token needs refresh: `Date.now() > session.expiresAt`
+     */
+    expiresAt: number;
+    /**
+     * Authenticated user information
+     * May be null if user info fetch failed
+     */
+    user: User | null;
+}
+
+/**
+ * Browser sessionStorage implementation
+ * Tokens persist until browser tab is closed
+ */
+export declare class SessionStorage implements TokenStorage {
+    private prefix;
+    constructor(prefix?: string);
+    private getKey;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Available storage backends for token persistence
+ *
+ * Choose based on security vs convenience tradeoffs:
+ *
+ * | Type | Persistence | Security | Use Case |
+ * |------|-------------|----------|----------|
+ * | `memory` | Page only | Highest | Sensitive apps |
+ * | `sessionStorage` | Tab lifetime | Medium | Standard apps |
+ * | `localStorage` | Permanent | Lower | Convenience priority |
+ */
+export declare type StorageType = "memory" | "localStorage" | "sessionStorage";
+
+/**
+ * Subscription handle for auth state change listener
+ *
+ * Returned by `onAuthStateChange()`. Call `unsubscribe()` to stop
+ * receiving auth state change events (e.g., on component unmount).
+ *
+ * @example
+ * ```typescript
+ * // React useEffect pattern
+ * useEffect(() => {
+ *   const { subscription } = client.onAuthStateChange((event, session) => {
+ *     setSession(session);
+ *   });
+ *
+ *   return () => {
+ *     subscription.unsubscribe();
+ *   };
+ * }, []);
+ * ```
+ */
+export declare interface Subscription {
+    /**
+     * Stop listening to auth state changes
+     * Call this on cleanup to prevent memory leaks
+     */
+    unsubscribe: () => void;
+}
+
+/**
+ * OAuth token set returned from token exchange
+ *
+ * Internal type used by SDK. For external use, prefer `Session` type.
+ */
+export declare interface TokenSet {
+    /**
+     * JWT access token for API authentication
+     */
+    accessToken: string;
+    /**
+     * Refresh token for obtaining new access tokens
+     * Used internally for automatic token refresh
+     */
+    refreshToken?: string;
+    /**
+     * Token type, typically 'Bearer'
+     */
+    tokenType: string;
+    /**
+     * Access token expiration time in seconds
+     */
+    expiresIn: number;
+    /**
+     * Unix timestamp (ms) when tokens were issued
+     * Used to calculate expiration: `issuedAt + expiresIn * 1000`
+     */
+    issuedAt: number;
+    /**
+     * Space-separated list of granted OAuth scopes
+     * @example "openid profile email"
+     */
+    scope?: string;
+}
+
+/**
+ * Custom token storage interface
+ *
+ * Implement this interface to provide custom storage backend
+ * (e.g., encrypted storage, IndexedDB, React Native AsyncStorage).
+ *
+ * All methods are async to support various storage backends.
+ *
+ * @example
+ * ```typescript
+ * import { TokenStorage } from 'genation';
+ *
+ * class EncryptedStorage implements TokenStorage {
+ *   async get(key: string) {
+ *     const encrypted = localStorage.getItem(key);
+ *     return encrypted ? decrypt(encrypted) : null;
+ *   }
+ *
+ *   async set(key: string, value: string) {
+ *     localStorage.setItem(key, encrypt(value));
+ *   }
+ *
+ *   async remove(key: string) {
+ *     localStorage.removeItem(key);
+ *   }
+ *
+ *   async clear() {
+ *     // Clear all SDK-related keys
+ *   }
+ * }
+ * ```
+ */
+export declare interface TokenStorage {
+    /**
+     * Retrieve a value by key
+     * @param key - Storage key
+     * @returns Stored value or null if not found
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Store a value with the given key
+     * @param key - Storage key
+     * @param value - Value to store
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Remove a value by key
+     * @param key - Storage key to remove
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Clear all stored values
+     * Called on sign out to clean up all SDK data
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * @fileoverview User information types for Genation SDK
+ * @module types/user
+ */
+/**
+ * OIDC Standard Claims User Profile
+ * https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
+ */
+export declare interface User {
+    /**
+     * Subject - Identifier for the End-User at the Issuer.
+     * Guaranteed to be unique and stable.
+     */
+    sub: string;
+    /**
+     * End-User's full name in displayable form including all name parts
+     */
+    name?: string;
+    /**
+     * Given name(s) or first name(s) of the End-User
+     */
+    given_name?: string;
+    /**
+     * Surname(s) or last name(s) of the End-User
+     */
+    family_name?: string;
+    /**
+     * Shorthand name by which the End-User wishes to be referred to
+     */
+    preferred_username?: string;
+    /**
+     * URL of the End-User's profile picture
+     */
+    picture?: string;
+    /**
+     * End-User's preferred e-mail address
+     */
+    email?: string;
+    /**
+     * True if the End-User's e-mail address has been verified
+     */
+    email_verified?: boolean;
+    /**
+     * End-User's preferred telephone number
+     */
+    phone_number?: string;
+    /**
+     * True if the End-User's phone number has been verified
+     */
+    phone_number_verified?: boolean;
+    /**
+     * Time the End-User's information was last updated
+     * ISO 8601 string or number
+     */
+    updated_at?: string;
+    /**
+     * Additional claims from the provider
+     */
+    [key: string]: unknown;
+}
+
+export { }