@kaiz11/stack-client 0.0.14

package/LICENSE

@@ -0,0 +1,32 @@
+Copyright (c) 2026 Kai Zhao. All rights reserved.
+
+PROPRIETARY SOFTWARE LICENSE
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Kai Zhao.
+
+RESTRICTIONS
+
+You may NOT, without prior written permission from the copyright holder:
+
+1. Copy, reproduce, or duplicate the Software or any portion thereof
+2. Modify, adapt, translate, or create derivative works based on the Software
+3. Distribute, sublicense, lease, rent, loan, or otherwise transfer the Software
+4. Reverse engineer, disassemble, decompile, or attempt to derive the source
+   code of the Software
+5. Remove or alter any proprietary notices, labels, or marks on the Software
+6. Use the Software for any commercial purpose
+7. Make the Software available to any third party
+
+DISCLAIMER
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+CONTACT
+
+For licensing inquiries, please contact the copyright holder.

package/README.md

@@ -0,0 +1,586 @@
+# @kaiz11/stack-client
+
+A standalone TypeScript client for Supabase stack services. Supports both platform-level and tenant-level operations with automatic token management.
+
+## Installation
+
+This package is published to GitHub Packages. Configure your `.npmrc` to use the GitHub registry for the `@kaiz11` scope:
+
+```bash
+# .npmrc (project root or ~/.npmrc)
+@kaiz11:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+Then install:
+
+```bash
+pnpm add @kaiz11/stack-client
+```
+
+### Authentication
+
+GitHub Packages requires authentication even for public packages. Create a [Personal Access Token](https://github.com/settings/tokens) with the `read:packages` scope and set it as `GITHUB_TOKEN`:
+
+```bash
+# Option 1: Environment variable
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+
+# Option 2: npm login
+npm login --registry=https://npm.pkg.github.com
+```
+
+For CI/CD, use the built-in `GITHUB_TOKEN` secret or a PAT with `read:packages` scope.
+
+## Quick Start
+
+```typescript
+import { createTenantClient } from "@kaiz11/stack-client";
+
+const client = createTenantClient({
+  baseUrl: "https://stack.example.com",
+  tenantId: "my-tenant",
+});
+
+// Sign in
+await client.auth.signInWithPassword({
+  email: "user@example.com",
+  password: "password123",
+});
+
+// Access the user
+const user = client.auth.getUser();
+```
+
+## Client Modes
+
+### Tenant Mode
+
+For applications serving a single tenant. Endpoints use `/auth/{tenantId}/*`.
+
+```typescript
+import { createTenantClient } from "@kaiz11/stack-client";
+
+const client = createTenantClient({
+  baseUrl: "https://stack.example.com",
+  tenantId: "acme-corp",
+});
+```
+
+### Platform Mode
+
+For platform-level operations (admin dashboards, multi-tenant management). Endpoints use `/auth/_platform/*`.
+
+```typescript
+import { createPlatformClient } from "@kaiz11/stack-client";
+
+const client = createPlatformClient({
+  baseUrl: "https://stack.example.com",
+});
+```
+
+### Generic Mode
+
+When you need to specify the mode dynamically, use `createClient()` with `tenantId` for tenant mode, or without it for platform mode:
+
+```typescript
+import { createClient } from "@kaiz11/stack-client";
+
+// Tenant mode (tenantId present)
+const tenantClient = createClient({
+  baseUrl: "https://stack.example.com",
+  tenantId: "acme-corp",
+});
+
+// Platform mode (no tenantId)
+const platformClient = createClient({
+  baseUrl: "https://stack.example.com",
+});
+```
+
+## Configuration
+
+```typescript
+interface ClientConfig {
+  /** Base URL of the stack server */
+  baseUrl: string;
+
+  /** Token storage type: "memory" | "localStorage" | custom TokenStore */
+  tokenStore?: TokenStoreType;
+
+  /** Storage key prefix (default: "stack") */
+  storagePrefix?: string;
+
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+
+  /** Enable mock mode for testing (no HTTP requests) */
+  mock?: boolean;
+
+  /** Mock options (latency simulation, etc.) */
+  mockOptions?: MockOptions;
+}
+
+interface TenantClientConfig extends ClientConfig {
+  /** Tenant identifier */
+  tenantId: string;
+}
+```
+
+## Token Storage
+
+Tokens need to be stored somewhere. The client supports pluggable storage backends:
+
+### Memory Store (Default)
+
+Tokens are stored in memory. Lost on page refresh. Good for server-side usage.
+
+```typescript
+import { createTenantClient, MemoryTokenStore } from "@kaiz11/stack-client";
+
+const client = createTenantClient({
+  baseUrl: "https://stack.example.com",
+  tenantId: "my-tenant",
+  tokenStore: new MemoryTokenStore(), // This is the default
+});
+```
+
+### LocalStorage Store
+
+Tokens persist in browser localStorage. Survives page refreshes.
+
+```typescript
+import {
+  createTenantClient,
+  LocalStorageTokenStore,
+} from "@kaiz11/stack-client";
+
+const client = createTenantClient({
+  baseUrl: "https://stack.example.com",
+  tenantId: "my-tenant",
+  tokenStore: new LocalStorageTokenStore("my-app-auth"),
+});
+```
+
+### Custom Store
+
+Implement the `TokenStore` interface for custom backends (cookies, IndexedDB, etc.):
+
+```typescript
+import { TokenStore } from "@kaiz11/stack-client";
+
+class CookieTokenStore implements TokenStore {
+  getAccessToken(): string | null {
+    return getCookie("access_token");
+  }
+
+  getRefreshToken(): string | null {
+    return getCookie("refresh_token");
+  }
+
+  setTokens(accessToken: string, refreshToken: string): void {
+    setCookie("access_token", accessToken, { httpOnly: true, secure: true });
+    setCookie("refresh_token", refreshToken, { httpOnly: true, secure: true });
+  }
+
+  clearTokens(): void {
+    deleteCookie("access_token");
+    deleteCookie("refresh_token");
+  }
+}
+```
+
+## Cleanup
+
+When done with the client, call `destroy()` to clear auto-refresh timers:
+
+```typescript
+const client = createTenantClient({ ... });
+
+// When cleaning up (e.g., component unmount)
+client.destroy();
+```
+
+## Server-Side Usage
+
+The same client works on both frontend and backend. For server-side usage, use `tokenStore: "memory"` and pass `accessToken` directly.
+
+> **Note:** The client does not verify tokens passed via `accessToken`. It assumes the token is valid and uses it for outgoing API calls. Verification happens server-side when the request reaches PostgREST, Storage, or other backend services. If you need to verify incoming requests, use the [Auth Middleware](#auth-middleware-verifying-incoming-requests).
+
+### Service Role (Admin Access)
+
+Use a service role token for admin operations that bypass RLS:
+
+```typescript
+import { createTenantClient } from "@kaiz11/stack-client";
+
+const adminClient = createTenantClient({
+  baseUrl: "https://stack.example.com",
+  tenantId: "acme-corp",
+  tokenStore: "memory",
+  accessToken: process.env.SERVICE_ROLE_TOKEN,
+});
+
+// Admin operations - bypasses RLS
+await adminClient.storage.from("uploads").upload("file.pdf", data);
+await adminClient.storage.from("private").list(); // Can access all files
+```
+
+### User Context (Respects RLS)
+
+Pass the user's access token (from a verified request) to make calls scoped to that user:
+
+```typescript
+import { createTenantClient } from "@kaiz11/stack-client";
+
+// In your API handler, after verifying the request
+const userClient = createTenantClient({
+  baseUrl: "https://stack.example.com",
+  tenantId: "acme-corp",
+  tokenStore: "memory",
+  accessToken: userAccessToken, // From verified JWT
+});
+
+// User-scoped operations - respects RLS
+await userClient.storage.from("user-files").list(); // Only sees their files
+await userClient.accounts.list(); // Only sees their accounts
+```
+
+### Auth Middleware (Verifying Incoming Requests)
+
+Use the auth middleware to verify JWTs on incoming requests. The middleware automatically fetches the JWKS from GoTrue for ES256 verification.
+
+```typescript
+import { Hono } from "hono";
+import { createStackAuthMiddleware } from "@kaiz11/stack-client/auth/server";
+
+const app = new Hono();
+
+// For tenant APIs
+app.use(
+  "*",
+  createStackAuthMiddleware({
+    baseUrl: "https://stack.example.com",
+    tenantId: "acme-corp",
+    excludePaths: [/^\/health$/], // Optional: skip auth for these paths
+  }),
+);
+
+// For platform APIs
+app.use(
+  "*",
+  createStackAuthMiddleware({
+    baseUrl: "https://stack.example.com",
+    // No tenantId = platform mode
+  }),
+);
+
+// Access verified user in handlers
+app.get("/api/me", (c) => {
+  const user = c.get("user"); // { id, email, role, aal, ... }
+  const token = c.get("accessToken"); // Raw JWT for downstream calls
+  return c.json({ user });
+});
+```
+
+### Optional Auth Middleware
+
+For routes that work with or without authentication:
+
+```typescript
+import { optionalStackAuthMiddleware } from "@kaiz11/stack-client/auth/server";
+
+app.use(
+  "*",
+  optionalStackAuthMiddleware({
+    baseUrl: "https://stack.example.com",
+    tenantId: "acme-corp",
+  }),
+);
+
+app.get("/api/feed", (c) => {
+  const user = c.get("user"); // undefined if not authenticated
+  if (user) {
+    return c.json({ feed: getPersonalizedFeed(user.id) });
+  }
+  return c.json({ feed: getPublicFeed() });
+});
+```
+
+### Role & MFA Guards
+
+Add additional guards after the auth middleware:
+
+```typescript
+import {
+  createStackAuthMiddleware,
+  requireRoleMiddleware,
+  requireMfaMiddleware,
+} from "@kaiz11/stack-client/auth/server";
+
+// All routes require authentication
+app.use("*", createStackAuthMiddleware({ baseUrl, tenantId }));
+
+// Admin routes require service_role
+app.use("/admin/*", requireRoleMiddleware("service_role"));
+
+// Sensitive routes require MFA (AAL2)
+app.use("/settings/security/*", requireMfaMiddleware());
+```
+
+### Complete Server Example
+
+```typescript
+import { Hono } from "hono";
+import { createTenantClient } from "@kaiz11/stack-client";
+import { createStackAuthMiddleware } from "@kaiz11/stack-client/auth/server";
+
+const app = new Hono();
+
+const baseUrl = "https://stack.example.com";
+const tenantId = "acme-corp";
+
+// Verify incoming requests
+app.use("/api/*", createStackAuthMiddleware({ baseUrl, tenantId }));
+
+// User uploads a file (respects RLS)
+app.post("/api/upload", async (c) => {
+  const userClient = createTenantClient({
+    baseUrl,
+    tenantId,
+    tokenStore: "memory",
+    accessToken: c.get("accessToken"),
+  });
+
+  const file = await c.req.blob();
+  const { data, error } = await userClient.storage
+    .from("uploads")
+    .upload(`${c.get("user").id}/file.pdf`, file);
+
+  return c.json({ data, error });
+});
+
+// Admin generates a report (bypasses RLS)
+app.post("/api/admin/report", async (c) => {
+  const adminClient = createTenantClient({
+    baseUrl,
+    tenantId,
+    tokenStore: "memory",
+    accessToken: process.env.SERVICE_ROLE_TOKEN,
+  });
+
+  // Can access all users' files
+  const { data } = await adminClient.storage.from("uploads").list();
+  return c.json({ files: data });
+});
+
+export default app;
+```
+
+## Testing
+
+The client includes built-in mock mode for testing without HTTP requests.
+
+### Mock Mode
+
+Enable mock mode for unit tests or local development:
+
+```typescript
+const client = createTenantClient({
+  baseUrl: "https://stack.example.com",
+  tenantId: "test-tenant",
+  mock: true,
+});
+
+// All auth methods work without network requests
+await client.auth.signIn({ email: "test@example.com", password: "password" });
+const user = client.auth.getUser(); // Returns mock user
+```
+
+### Simulating Latency
+
+Add artificial delay to simulate network conditions:
+
+```typescript
+const client = createTenantClient({
+  baseUrl: "https://stack.example.com",
+  tenantId: "test-tenant",
+  mock: true,
+  mockOptions: {
+    latency: 100, // 100ms delay on all operations
+  },
+});
+```
+
+### Controlling Mock Behavior
+
+Use `mockState` to simulate errors and edge cases:
+
+```typescript
+import { createTenantClient, mockState } from "@kaiz11/stack-client";
+
+const client = createTenantClient({ ..., mock: true });
+
+// Simulate sign-in failure
+mockState.shouldFailSignIn = true;
+await client.auth.signIn({ email, password }); // Throws AuthError
+
+// Simulate sign-up failure (user exists)
+mockState.shouldFailSignUp = true;
+await client.auth.signUp({ email, password }); // Throws AuthError
+
+// Simulate token refresh failure
+mockState.shouldFailRefresh = true;
+await client.auth.refreshSession(); // Throws AuthError
+
+// Reset to default behavior
+mockState.reset();
+```
+
+### Tracking Request Counts
+
+Use `requestCounts` to verify operations were called:
+
+```typescript
+import { createTenantClient, requestCounts } from "@kaiz11/stack-client";
+
+const client = createTenantClient({ ..., mock: true });
+
+await client.auth.signIn({ email, password });
+console.log(requestCounts.signIn); // 1
+
+await client.auth.signOut();
+console.log(requestCounts.signOut); // 1
+
+// Reset counts between tests
+requestCounts.reset();
+```
+
+### Vitest Example
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  createTenantClient,
+  mockState,
+  requestCounts,
+} from "@kaiz11/stack-client";
+
+describe("auth", () => {
+  let client: ReturnType<typeof createTenantClient>;
+
+  beforeEach(() => {
+    client = createTenantClient({
+      baseUrl: "https://stack.example.com",
+      tenantId: "test",
+      mock: true,
+    });
+  });
+
+  afterEach(() => {
+    client.destroy();
+    mockState.reset();
+    requestCounts.reset();
+  });
+
+  it("signs in user", async () => {
+    await client.auth.signIn({ email: "test@example.com", password: "pass" });
+
+    expect(client.auth.isAuthenticated()).toBe(true);
+    expect(requestCounts.signIn).toBe(1);
+  });
+
+  it("handles sign-in error", async () => {
+    mockState.shouldFailSignIn = true;
+
+    await expect(
+      client.auth.signIn({ email: "test@example.com", password: "wrong" }),
+    ).rejects.toThrow();
+  });
+});
+```
+
+## Known Limitations
+
+Some client features require backend configuration or are not yet supported by the self-hosted Stack platform.
+
+### Features Requiring Backend Configuration
+
+| Feature                     | Requirement                                   | Status                       |
+| --------------------------- | --------------------------------------------- | ---------------------------- |
+| **Phone/SMS Auth**          | Twilio configuration in GoTrue                | Not configured               |
+| **Manual Identity Linking** | `GOTRUE_SECURITY_MANUAL_LINKING_ENABLED=true` | Disabled by default          |
+| **TUS Resumable Uploads**   | Storage service TUS endpoint                  | Returns 500 (platform issue) |
+
+### Features Requiring Browser Interaction
+
+These features work correctly but cannot be fully automated in tests:
+
+| Feature                    | Reason                                |
+| -------------------------- | ------------------------------------- |
+| **OAuth Sign-In**          | Requires browser redirect to provider |
+| **OAuth Identity Linking** | Requires browser OAuth flow           |
+| **PKCE OAuth Flow**        | Requires browser for code exchange    |
+
+### API Differences from Official Supabase
+
+| Method                   | Difference                                        |
+| ------------------------ | ------------------------------------------------- |
+| `auth.mfa.listFactors()` | Returns 405 (endpoint not available in GoTrue)    |
+| `auth.reauthenticate()`  | Sends OTP email, returns `void` (not `{ nonce }`) |
+
+### Workarounds
+
+**For `reauthenticate()`**: The OTP sent to email should be used as the `nonce` parameter in `updatePassword()`:
+
+```typescript
+// Request reauthentication (sends OTP to email)
+await client.auth.reauthenticate();
+
+// User receives OTP via email, enters it
+const otp = "123456"; // from email
+
+// Use OTP as nonce for password update
+await client.auth.updatePassword({
+  password: "new-password",
+  nonce: otp,
+});
+```
+
+## Modules
+
+| Module      | Description                                         | Documentation                               |
+| ----------- | --------------------------------------------------- | ------------------------------------------- |
+| `auth`      | Authentication (sign in, sign up, sign out, tokens) | [Auth README](./src/auth/README.md)         |
+| `accounts`  | Multi-tenant accounts (teams, roles, members)       | [Accounts README](./src/accounts/README.md) |
+| `storage`   | File storage (buckets, uploads, signed URLs, TUS)   | [Storage README](./src/storage/README.md)   |
+| `functions` | Edge functions                                      | Coming soon                                 |
+| `realtime`  | Realtime subscriptions                              | Coming soon                                 |
+
+## TypeScript Types
+
+```typescript
+import type {
+  // Client
+  StackClient,
+  ClientConfig,
+  TenantClientConfig,
+  PlatformClientConfig,
+  ClientMode,
+
+  // Token storage
+  TokenStore,
+  TokenStoreType,
+
+  // Mock mode
+  MockOptions,
+  MockState,
+  RequestCounts,
+} from "@kaiz11/stack-client";
+```
+
+## License
+
+Copyright © 2026 Kai Zhao. All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying, distribution, modification, or use of this software, via any medium, is strictly prohibited without prior written permission from the copyright holder.