authtara-sdk 1.0.0

package/README.md

@@ -0,0 +1,420 @@
+# authtara-sdk
+
+> **SDK Client untuk integrasi dengan DigitalSolution Platform** - SSO Authentication, Billing/Entitlement Check, dan Usage Metering untuk aplikasi external.
+
+[![npm version](https://img.shields.io/npm/v/authtara-sdk.svg)](https://www.npmjs.com/package/authtara-sdk)
+[![CI](https://github.com/digitalsolution/authtara-sdk/workflows/CI/badge.svg)](https://github.com/digitalsolution/authtara-sdk/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## 🚀 Features
+
+- **🔐 SSO Authentication** - Offline JWT verification dengan HS256 + App Secret
+- **💳 Billing & Entitlement** - Check tenant access rights dan feature availability
+- **📊 Usage Metering** - Track usage untuk usage-based billing
+- **🎯 Type-Safe** - Full TypeScript support dengan comprehensive types
+- **⚡ Modern** - Built dengan ES Modules, CommonJS, dan TypeScript definitions
+- **🧪 Tested** - Comprehensive unit tests dengan 80%+ coverage
+
+## 📦 Installation
+
+```bash
+# Menggunakan Bun (recommended)
+bun add authtara-sdk
+
+# Menggunakan npm
+npm install authtara-sdk
+
+# Menggunakan yarn
+yarn add authtara-sdk
+```
+
+## 🔧 Quick Start
+
+### 1. Initialize SDK
+
+```typescript
+import { Authtara } from "authtara-sdk";
+
+const ds = new Authtara({
+  apiKey: process.env.DS_APP_SECRET!, // Get from Developer Dashboard
+  endpoint: "https://api.digitalsolution.com", // Optional, defaults to production
+});
+```
+
+### 2. Verify SSO Token (Offline)
+
+```typescript
+// Di callback endpoint setelah SSO
+const code = searchParams.get("code");
+const result = await ds.auth.exchangeCode(code!);
+
+// Simpan token ke session
+session.set("ds_token", result.token);
+
+// Verify token (offline, no network call)
+const session = await ds.auth.verifySession(result.token);
+
+console.log("User:", session.user);
+console.log("Tenant:", session.tenant);
+console.log("Plan:", session.subscription.plan);
+```
+
+### 3. Check Entitlement
+
+```typescript
+// Basic access check
+const access = await ds.billing.checkEntitlement({
+  tenantId: session.tenant!.id,
+});
+
+if (!access.granted) {
+  return redirect("/upgrade", { reason: access.reason });
+}
+
+// Feature-specific check
+const canUseAI = await ds.billing.checkEntitlement({
+  tenantId: session.tenant!.id,
+  featureKey: "ai_generator",
+});
+
+if (!canUseAI.granted) {
+  throw new Error("AI feature not available in your plan");
+}
+```
+
+### 4. Record Usage
+
+```typescript
+// Record API call
+await ds.metering.recordUsage({
+  tenantId: session.tenant!.id,
+  metricSlug: "api_call",
+  amount: 1,
+});
+
+// Batch recording
+await ds.metering.recordUsage({
+  tenantId: session.tenant!.id,
+  metricSlug: "message_sent",
+  amount: 50,
+});
+```
+
+## 📚 API Reference
+
+### `Authtara` Constructor
+
+```typescript
+new Authtara(config: AuthtaraConfig)
+```
+
+**Config Options:**
+
+| Option     | Type     | Required | Default                           | Description                         |
+| ---------- | -------- | -------- | --------------------------------- | ----------------------------------- |
+| `apiKey`   | `string` | ✅ Yes   | -                                 | App Secret dari Developer Dashboard |
+| `endpoint` | `string` | No       | `https://api.digitalsolution.com` | Base URL Platform API               |
+| `timeout`  | `number` | No       | `30000`                           | Request timeout dalam milliseconds  |
+
+### Auth Module
+
+#### `auth.verifySession(token: string)`
+
+Verify JWT token secara offline menggunakan App Secret.
+
+**Returns:** `Promise<SessionVerifyResult>`
+
+```typescript
+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;
+  };
+}
+```
+
+**Throws:**
+
+- `InvalidTokenError` - Token invalid atau expired
+
+---
+
+#### `auth.exchangeCode(code: string)`
+
+Exchange authorization code untuk JWT token (server-to-server).
+
+**Returns:** `Promise<ExchangeResult>`
+
+```typescript
+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 };
+}
+```
+
+**Throws:**
+
+- `ConfigurationError` - Code tidak disediakan
+- `ApiError` - Network atau API error
+
+### Billing Module
+
+#### `billing.checkEntitlement(params: CheckEntitlementParams)`
+
+Check apakah tenant memiliki akses ke aplikasi atau fitur spesifik.
+
+**Params:**
+
+```typescript
+interface CheckEntitlementParams {
+  tenantId: string; // Required
+  featureKey?: string; // Optional: untuk cek fitur spesifik
+}
+```
+
+**Returns:** `Promise<EntitlementResult>`
+
+```typescript
+interface EntitlementResult {
+  granted: boolean;
+  reason?: string;
+  entitlement?: {
+    status: string;
+    subscription?: {
+      plan: string;
+      status: string;
+    };
+  };
+}
+```
+
+### Metering Module
+
+#### `metering.recordUsage(params: RecordUsageParams)`
+
+Catat penggunaan untuk usage-based billing.
+
+**Params:**
+
+```typescript
+interface RecordUsageParams {
+  tenantId: string;
+  metricSlug: string; // e.g., 'api_call', 'message_sent'
+  amount: number; // Harus positif
+  timestamp?: string; // Optional ISO timestamp
+}
+```
+
+**Available Metrics:**
+
+- `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)
+
+**Returns:** `Promise<RecordUsageResult>`
+
+```typescript
+interface RecordUsageResult {
+  success: boolean;
+  recordId?: string;
+}
+```
+
+## 🔒 Error Handling
+
+SDK menyediakan custom error classes untuk memudahkan error handling:
+
+```typescript
+import { AuthtaraError, InvalidTokenError, EntitlementDeniedError, ApiError, ConfigurationError } from "authtara-sdk";
+
+try {
+  const session = await ds.auth.verifySession(token);
+} catch (error) {
+  if (error instanceof InvalidTokenError) {
+    // Token invalid atau expired - redirect ke login
+    return redirect("/login");
+  }
+
+  if (error instanceof ApiError) {
+    console.error("API Error:", error.statusCode, error.message);
+  }
+
+  if (error instanceof ConfigurationError) {
+    console.error("Configuration Error:", error.message);
+  }
+}
+```
+
+**Error Hierarchy:**
+
+- `AuthtaraError` (base class)
+  - `InvalidTokenError` - Token validation errors
+  - `EntitlementDeniedError` - Access denied errors
+  - `ApiError` - API communication errors
+  - `ConfigurationError` - SDK misconfiguration
+
+## 🛠️ Advanced Usage
+
+### Custom Timeout
+
+```typescript
+const ds = new Authtara({
+  apiKey: process.env.DS_APP_SECRET!,
+  timeout: 10000, // 10 seconds
+});
+```
+
+### Environment Variables
+
+Recommended `.env` setup:
+
+```bash
+DS_APP_SECRET=your_app_secret_here
+DS_API_URL=https://api.digitalsolution.com
+```
+
+### TypeScript Configuration
+
+SDK mendukung TypeScript dengan strict mode. Pastikan `tsconfig.json` Anda memiliki:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "esModuleInterop": true
+  }
+}
+```
+
+## 🧪 Testing
+
+Untuk testing aplikasi Anda dengan SDK:
+
+```typescript
+import { vi } from "vitest";
+
+// Mock Authtara SDK
+vi.mock("authtara-sdk", () => ({
+  Authtara: vi.fn().mockImplementation(() => ({
+    auth: {
+      verifySession: vi.fn().mockResolvedValue({
+        isValid: true,
+        user: { id: "1", email: "test@example.com", name: "Test" },
+        tenant: { id: "1", name: "Test Tenant", subdomain: "test", role: "OWNER" },
+      }),
+    },
+  })),
+}));
+```
+
+## 📖 Integration Examples
+
+### Next.js App Router
+
+```typescript
+// app/api/sso/callback/route.ts
+import { Authtara } from "authtara-sdk";
+
+const ds = new Authtara({
+  apiKey: process.env.DS_APP_SECRET!,
+});
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const code = searchParams.get("code");
+
+  if (!code) {
+    return Response.json({ error: "Missing code" }, { status: 400 });
+  }
+
+  const result = await ds.auth.exchangeCode(code);
+
+  // Set session cookie
+  // ... your session logic
+
+  return Response.redirect("/dashboard");
+}
+```
+
+### Express.js
+
+```typescript
+import express from "express";
+import { Authtara } from "authtara-sdk";
+
+const app = express();
+const ds = new Authtara({
+  apiKey: process.env.DS_APP_SECRET!,
+});
+
+app.get("/api/sso/callback", async (req, res) => {
+  const { code } = req.query;
+  const result = await ds.auth.exchangeCode(code as string);
+
+  req.session.token = result.token;
+  res.redirect("/dashboard");
+});
+
+app.use(async (req, res, next) => {
+  if (!req.session.token) return next();
+
+  try {
+    const session = await ds.auth.verifySession(req.session.token);
+    req.user = session.user;
+    req.tenant = session.tenant;
+    next();
+  } catch (error) {
+    req.session.destroy();
+    res.redirect("/login");
+  }
+});
+```
+
+## 🔄 Migration Guide
+
+### From v0.x to v1.x
+
+Tidak ada breaking changes - v1.0.0 adalah initial stable release.
+
+## 📝 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## 🤝 Contributing
+
+SDK ini di-maintain oleh DigitalSolution Team. Untuk bug reports atau feature requests:
+
+1. Check existing [GitHub Issues](https://github.com/digitalsolution/authtara-sdk/issues)
+2. Create new issue dengan detail yang lengkap
+3. Atau hubungi support di support@digitalsolution.com
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- **NPM Package:** https://www.npmjs.com/package/authtara-sdk
+- **GitHub Repository:** https://github.com/digitalsolution/authtara-sdk
+- **Documentation:** https://docs.digitalsolution.com/sdk
+- **Developer Dashboard:** https://digitalsolution.com/dashboard/developer
+
+---
+
+**Built with ❤️ by DigitalSolution Team**