authtara-sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,450 @@
+/**
+ * Authtara SDK - HTTP Client
+ *
+ * HTTP client wrapper untuk komunikasi dengan DigitalSolution Platform API.
+ * Menggunakan fetch API yang tersedia di Node.js 18+ dan browser.
+ */
+interface HttpClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+}
+interface RequestOptions {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/**
+ * HTTP Client untuk SDK
+ *
+ * Fitur:
+ * - Auto-inject Authorization header
+ * - JSON serialization/deserialization
+ * - Error handling dengan custom errors
+ * - Timeout support
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(config: HttpClientConfig);
+    /**
+     * Make HTTP request to Platform API
+     */
+    request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * POST request shorthand
+     */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * GET request shorthand
+     */
+    get<T>(path: string): Promise<T>;
+}
+
+/**
+ * Authtara SDK - Auth Module
+ *
+ * Menangani validasi SSO token dan exchange authorization code.
+ * Sesuai dengan Blueprint Ekosistem Developer V2.0.
+ */
+
+/**
+ * Hasil verifikasi session dari SSO token
+ */
+interface SessionVerifyResult {
+    isValid: boolean;
+    user?: {
+        id: string;
+        email: string;
+        name: string | null;
+    };
+    tenant?: {
+        id: string;
+        name: string;
+        subdomain: string;
+        role: string;
+    };
+    subscription?: {
+        plan: string;
+        status: string;
+    };
+}
+/**
+ * Hasil exchange authorization code
+ */
+interface ExchangeResult {
+    token: string;
+    expiresIn: number;
+    user: {
+        id: string;
+        email: string;
+        name: string | null;
+    };
+    tenant: {
+        id: string;
+        name: string;
+        subdomain: string;
+        role: string;
+    };
+    subscription: {
+        plan: string;
+        status: string;
+    };
+}
+/**
+ * Auth Module
+ *
+ * Menyediakan fungsi untuk:
+ * - verifySession: Verifikasi JWT token secara offline menggunakan App Secret
+ * - exchangeCode: Menukar authorization code dengan JWT token (server-to-server)
+ */
+declare class AuthModule {
+    private readonly apiKey;
+    private readonly httpClient;
+    private readonly issuer;
+    constructor(apiKey: string, httpClient: HttpClient, issuer?: string);
+    /**
+     * Verifikasi SSO JWT token secara offline
+     *
+     * Token diverifikasi menggunakan App Secret (HS256).
+     * Ini lebih cepat daripada memanggil API karena tidak memerlukan network request.
+     *
+     * @param token - JWT token dari SSO callback
+     * @returns SessionVerifyResult dengan data user, tenant, dan subscription
+     * @throws InvalidTokenError jika token tidak valid atau expired
+     *
+     * @example
+     * ```typescript
+     * const session = await ds.auth.verifySession(token);
+     * if (session.isValid) {
+     *   console.log('User:', session.user);
+     *   console.log('Tenant:', session.tenant);
+     * }
+     * ```
+     */
+    verifySession(token: string): Promise<SessionVerifyResult>;
+    /**
+     * Exchange authorization code untuk JWT token (server-to-server)
+     *
+     * Gunakan ini di callback endpoint untuk menukar authorization code
+     * menjadi JWT token yang bisa diverifikasi.
+     *
+     * @param code - Authorization code dari callback URL
+     * @returns ExchangeResult dengan token dan data context
+     *
+     * @example
+     * ```typescript
+     * // Di endpoint /api/sso/callback
+     * const code = searchParams.get('code');
+     * const result = await ds.auth.exchangeCode(code);
+     * // Simpan result.token ke session
+     * ```
+     */
+    exchangeCode(code: string): Promise<ExchangeResult>;
+}
+
+/**
+ * Authtara SDK - Billing Module
+ *
+ * Menangani pengecekan entitlement (hak akses) tenant ke fitur aplikasi.
+ * Sesuai dengan Blueprint Ekosistem Developer V2.0.
+ */
+
+/**
+ * Parameter untuk pengecekan entitlement
+ */
+interface CheckEntitlementParams {
+    /** Tenant ID yang ingin dicek */
+    tenantId: string;
+    /** Optional: Feature key untuk cek fitur spesifik */
+    featureKey?: string;
+}
+/**
+ * Hasil pengecekan entitlement
+ */
+interface EntitlementResult {
+    /** Apakah akses diberikan */
+    granted: boolean;
+    /** Alasan jika akses tidak diberikan */
+    reason?: string;
+    /** Detail entitlement */
+    entitlement?: {
+        status: string;
+        subscription?: {
+            plan: string;
+            status: string;
+        };
+    };
+}
+/**
+ * Billing Module
+ *
+ * Menyediakan fungsi untuk mengecek hak akses tenant ke aplikasi Anda.
+ * Berguna untuk feature gating dan paywall logic.
+ *
+ * @example
+ * ```typescript
+ * const access = await ds.billing.checkEntitlement({
+ *   tenantId: currentTenant.id,
+ *   featureKey: 'premium_feature'
+ * });
+ *
+ * if (!access.granted) {
+ *   return <UpgradeModal reason={access.reason} />;
+ * }
+ * ```
+ */
+declare class BillingModule {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Cek apakah tenant memiliki akses ke aplikasi Anda
+     *
+     * @param params - Parameter pengecekan (tenantId wajib, featureKey opsional)
+     * @returns EntitlementResult dengan status akses
+     *
+     * @example
+     * ```typescript
+     * // Cek akses dasar
+     * const hasAccess = await ds.billing.checkEntitlement({
+     *   tenantId: tenant.id
+     * });
+     *
+     * // Cek fitur spesifik
+     * const canUseAI = await ds.billing.checkEntitlement({
+     *   tenantId: tenant.id,
+     *   featureKey: 'ai_generator'
+     * });
+     *
+     * if (!canUseAI.granted) {
+     *   throw new Error(canUseAI.reason);
+     * }
+     * ```
+     */
+    checkEntitlement(params: CheckEntitlementParams): Promise<EntitlementResult>;
+}
+
+/**
+ * Authtara SDK - Metering Module
+ *
+ * Menangani pencatatan penggunaan (usage-based billing).
+ * Sesuai dengan Blueprint Ekosistem Developer V2.0.
+ */
+
+/**
+ * Parameter untuk pencatatan usage
+ */
+interface RecordUsageParams {
+    /** Tenant ID yang penggunaannya dicatat */
+    tenantId: string;
+    /**
+     * Identifier metrik
+     *
+     * Metrik yang tersedia:
+     * - `message_sent` - Pesan yang dikirim (agregasi bulanan)
+     * - `api_call` - API calls (agregasi harian)
+     * - `connection_active` - Koneksi aktif (agregasi harian)
+     * - `websocket_connection` - WebSocket connections (agregasi harian)
+     */
+    metricSlug: string;
+    /** Jumlah yang dicatat (harus positif) */
+    amount: number;
+    /** Optional: Timestamp ISO (default: sekarang) */
+    timestamp?: string;
+}
+/**
+ * Hasil pencatatan usage
+ */
+interface RecordUsageResult {
+    /** Apakah berhasil dicatat */
+    success: boolean;
+    /** ID record yang dibuat */
+    recordId?: string;
+}
+/**
+ * Metering Module
+ *
+ * Menyediakan fungsi untuk mencatat penggunaan aplikasi oleh tenant.
+ * Data ini digunakan untuk usage-based billing.
+ *
+ * @example
+ * ```typescript
+ * // Catat penggunaan API call
+ * await ds.metering.recordUsage({
+ *   tenantId: tenant.id,
+ *   metricSlug: 'api_call',
+ *   amount: 1
+ * });
+ *
+ * // Catat batch messages
+ * await ds.metering.recordUsage({
+ *   tenantId: tenant.id,
+ *   metricSlug: 'message_sent',
+ *   amount: 50
+ * });
+ * ```
+ */
+declare class MeteringModule {
+    private readonly httpClient;
+    constructor(httpClient: HttpClient);
+    /**
+     * Catat penggunaan untuk usage-based billing
+     *
+     * @param params - Parameter pencatatan
+     * @returns RecordUsageResult
+     *
+     * @example
+     * ```typescript
+     * // Setelah user mengirim pesan
+     * await ds.metering.recordUsage({
+     *   tenantId: currentTenant.id,
+     *   metricSlug: 'message_sent',
+     *   amount: 1
+     * });
+     *
+     * // Batch recording untuk efisiensi
+     * await ds.metering.recordUsage({
+     *   tenantId: currentTenant.id,
+     *   metricSlug: 'api_call',
+     *   amount: 100 // Batch 100 API calls
+     * });
+     * ```
+     */
+    recordUsage(params: RecordUsageParams): Promise<RecordUsageResult>;
+}
+
+/**
+ * Authtara SDK - Custom Error Classes
+ *
+ * Error classes untuk SDK yang memudahkan error handling di aplikasi developer.
+ */
+/**
+ * Base error class untuk semua Authtara SDK errors
+ */
+declare class AuthtaraError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    constructor(message: string, code: string, statusCode?: number);
+}
+/**
+ * Error untuk token yang tidak valid atau expired
+ */
+declare class InvalidTokenError extends AuthtaraError {
+    constructor(message?: string);
+}
+/**
+ * Error untuk akses yang ditolak (entitlement denied)
+ */
+declare class EntitlementDeniedError extends AuthtaraError {
+    readonly reason?: string;
+    constructor(message?: string, reason?: string);
+}
+/**
+ * Error untuk API errors dari platform
+ */
+declare class ApiError extends AuthtaraError {
+    readonly response?: unknown;
+    constructor(message: string, statusCode: number, response?: unknown);
+}
+/**
+ * Error untuk configuration issues
+ */
+declare class ConfigurationError extends AuthtaraError {
+    constructor(message: string);
+}
+
+/**
+ * Authtara SDK
+ *
+ * SDK Client untuk integrasi dengan DigitalSolution Platform.
+ * Menyediakan SSO authentication, billing/entitlement check, dan usage metering.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { Authtara } from '@authtara/sdk';
+ *
+ * const ds = new Authtara({
+ *   apiKey: process.env.DS_APP_SECRET,
+ *   endpoint: 'https://api.digitalsolution.com'
+ * });
+ *
+ * // Verify SSO token
+ * const session = await ds.auth.verifySession(token);
+ *
+ * // Check entitlement
+ * const access = await ds.billing.checkEntitlement({
+ *   tenantId: session.tenant.id
+ * });
+ *
+ * // Record usage
+ * await ds.metering.recordUsage({
+ *   tenantId: session.tenant.id,
+ *   metricSlug: 'api_call',
+ *   amount: 1
+ * });
+ * ```
+ */
+
+/**
+ * Konfigurasi untuk Authtara SDK
+ */
+interface AuthtaraConfig {
+    /**
+     * App Secret dari Dashboard Developer
+     *
+     * Didapatkan setelah aplikasi disetujui (status: APPROVED)
+     */
+    apiKey: string;
+    /**
+     * Base URL Platform API
+     *
+     * @default 'https://api.digitalsolution.com'
+     */
+    endpoint?: string;
+    /**
+     * Request timeout dalam milliseconds
+     *
+     * @default 30000 (30 detik)
+     */
+    timeout?: number;
+}
+/**
+ * Authtara SDK Client
+ *
+ * Main entry point untuk semua integrasi dengan DigitalSolution Platform.
+ *
+ * @example
+ * ```typescript
+ * const ds = new Authtara({
+ *   apiKey: process.env.DS_APP_SECRET,
+ *   endpoint: 'https://api.digitalsolution.com'
+ * });
+ * ```
+ */
+declare class Authtara {
+    /**
+     * Auth module untuk SSO dan token verification
+     */
+    readonly auth: AuthModule;
+    /**
+     * Billing module untuk entitlement/access check
+     */
+    readonly billing: BillingModule;
+    /**
+     * Metering module untuk usage-based billing
+     */
+    readonly metering: MeteringModule;
+    /**
+     * Create new Authtara SDK instance
+     *
+     * @param config - Konfigurasi SDK
+     * @throws ConfigurationError jika apiKey tidak disediakan
+     */
+    constructor(config: AuthtaraConfig);
+}
+
+export { ApiError, Authtara, type AuthtaraConfig, AuthtaraError, type CheckEntitlementParams, ConfigurationError, EntitlementDeniedError, type EntitlementResult, type ExchangeResult, InvalidTokenError, type RecordUsageParams, type RecordUsageResult, type SessionVerifyResult, Authtara as default };