@mitway/sdk 0.5.0 → 0.7.1

package/README.md

@@ -1,29 +1,22 @@
 # @mitway/sdk
 
 TypeScript/JavaScript client for the **MITWAY-BaaS** backend. Lets end-user
-apps sign up, sign in, refresh tokens, and run PostgREST queries against a
-per-cliente MITWAY-BaaS deployment through a single public URL.
+apps sign up, sign in, refresh tokens, run PostgREST queries, subscribe to
+realtime events, and manage storage against a per-tenant MITWAY-BaaS deployment.
 
 ## Status
 
-**v0.2.0 — backend proxy.** Currently ships:
+**v0.5.0**
 
 | Module | Status | Notes |
 |---|---|---|
-| `auth` | ✅ Working | `signUp`, `signInWithPassword`, `signOut`, `refreshSession`, `getSession`, `getUser`, `getCurrentUser`, `getProfile`, `setProfile` |
-| `database` | ✅ Working | PostgREST query builder via `@supabase/postgrest-js`, routed through the backend proxy at `/api/database/records/*` and `/api/database/rpc/*` |
-| `storage` | ❌ Not yet | Backend has no `/api/storage/*` routes |
-| `functions` | ✅ MCP only | Backend routes + MCP tools working. No SDK module — functions are managed by the agent, not by end-user apps |
-| `email` | ❌ Not yet | Backend has no `/api/email/*` routes |
-| `ai` | ❌ Not yet | Backend has no `/api/ai/*` routes |
-| `realtime` | ❌ Not yet | No realtime subsystem |
-
-When the backend grows the missing routes, port the corresponding modules
-from upstream
-[`InsForge/InsForge-sdk-js`](https://github.com/InsForge/InsForge-sdk-js)
-(`src/modules/{storage,functions,email,ai,realtime}.ts`). The SDK was
-structured intentionally to match upstream so future ports are mechanical
-rebrands.
+| `auth` | Working | `signUp`, `signInWithPassword`, `signOut`, `refreshSession`, `getSession`, `getUser`, `getCurrentUser`, `getProfile`, `setProfile`, `onAuthStateChange` |
+| `database` | Working | PostgREST query builder via `@supabase/postgrest-js` |
+| `realtime` | Working | Socket.IO transport with channels (postgres_changes, broadcast, presence) |
+| `storage` | Working | Bucket admin + object operations (upload, download, signed URLs, public URLs) |
+| `functions` | MCP only | Backend routes + MCP tools working. No SDK module |
+| `email` | Not yet | Backend has no `/api/email/*` routes |
+| `ai` | Not yet | Backend has no `/api/ai/*` routes |
 
 ## Install
 
@@ -37,8 +30,8 @@ pnpm add @mitway/sdk
 import { createClient } from '@mitway/sdk';
 
 const client = createClient({
-  baseUrl: 'https://acme.api.dev.nttmitway.com',  // single backend URL
-  anonKey: 'eyJhbGciOiJIUzI1NiIs...',             // optional; signed JWT with role=anon
+  baseUrl: 'https://acme.api.dev.nttmitway.com',
+  anonKey: 'eyJhbGciOiJIUzI1NiIs...',
 });
 
 // Sign up
@@ -89,6 +82,14 @@ const { data: pub } = client.storage
   .from('avatars')
   .getPublicUrl('user-123/avatar.png');
 
+// Realtime subscription
+const channel = client.realtime
+  .channel('posts-feed')
+  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'posts' }, (payload) => {
+    console.log('New post:', payload);
+  })
+  .subscribe();
+
 // Sign out
 await client.auth.signOut();
 ```
@@ -106,17 +107,89 @@ interface MitwayBaasConfig {
   retryCount?: number;       // default 3 (0 disables)
   retryDelay?: number;       // default 500 ms (exponential backoff with jitter)
   autoRefreshToken?: boolean;// default true (refreshes on 401 INVALID_TOKEN)
+  persistSession?: boolean;  // default true (session survives F5)
+  storageKey?: string;       // default 'mitway_baas_session'
+  storage?: StorageAdapter;  // default browser localStorage — pluggable
+  multiTab?: boolean;        // default true (sync session across tabs via `storage` event)
+  realtime?: RealtimeOptions;
+}
+
+interface StorageAdapter {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
 }
 ```
 
-`baseUrl` is the **only** URL consumers need. Auth, database, and (in the
-future) storage/functions all route through the same backend. PostgREST
-is an internal ClusterIP Pod per cliente and is never publicly exposed —
-the backend proxies database requests to it over the cluster network.
+### Reactive auth — `onAuthStateChange`
 
-## Auth flow
+Subscribe to session transitions (sign-in, sign-out, token refresh,
+cross-tab sync, profile update) without polling `getSession()`. Returns
+a `Subscription`; call `.unsubscribe()` to stop.
+
+```typescript
+const sub = client.auth.onAuthStateChange((event, session) => {
+  // event: 'INITIAL_SESSION' | 'SIGNED_IN' | 'SIGNED_OUT'
+  //      | 'TOKEN_REFRESHED' | 'USER_UPDATED'
+  if (event === 'SIGNED_OUT') router.push('/login');
+});
+
+// later
+sub.unsubscribe();
+```
+
+### Custom storage (e.g., cross-subdomain cookie)
+
+Pass a `storage` adapter to back the session with something other than
+the default `localStorage` — cookies, a native secure store, an
+in-memory stub for tests. The adapter is called on every session
+mutation (sign-in, refresh, logout), so anything layered on top of it
+sees a complete session lifecycle.
+
+```typescript
+import { createClient, createLocalStorageAdapter } from '@mitway/sdk';
+import type { StorageAdapter } from '@mitway/sdk';
+
+const localAdapter = createLocalStorageAdapter();
+
+const dualStorage: StorageAdapter = {
+  getItem: (k) => localAdapter.getItem(k) ?? readFromCookie(k),
+  setItem: (k, v) => { localAdapter.setItem(k, v); writeCookie(k, v); },
+  removeItem: (k) => { localAdapter.removeItem(k); clearCookie(k); },
+};
+
+const client = createClient({
+  baseUrl: 'https://…',
+  storage: dualStorage,
+});
+```
 
-The SDK targets the routes the MITWAY-BaaS backend currently exposes:
+`baseUrl` is the **only** URL consumers need. Auth, database, storage, and realtime
+all route through the same backend.
+
+## Releasing a new version
+
+Releases are automated via GitHub Actions with OIDC provenance.
+
+**Steps:**
+
+1. Bump the version in `package.json`:
+
+```bash
+pnpm version patch   # or minor / major
+```
+
+2. Push the commit and tag:
+
+```bash
+git push --follow-tags
+```
+
+3. Create a **Release** on GitHub pointing to the new tag (e.g. `v0.5.1`).
+
+The workflow (`.github/workflows/publish.yml`) triggers on the release event, runs `typecheck`, `test`, `build`, and publishes to npm with provenance attestation. Requires an `NPM_TOKEN` secret configured in the repository.
+
+## Auth flow
 
 | Method | Backend route |
 |---|---|
@@ -125,43 +198,22 @@ The SDK targets the routes the MITWAY-BaaS backend currently exposes:
 | `signOut()` | `POST /api/auth/logout` |
 | `refreshSession()` (also automatic on 401) | `POST /api/auth/refresh` |
 
-The InsForge SDK uses different paths (`/api/auth/users`, `/api/auth/sessions`,
-etc.); those are not implemented in MITWAY-BaaS.
-
 The `HttpClient` automatically calls `refreshSession()` and retries the
-original request when it receives a `401 INVALID_TOKEN` response, so you
-don't need to manage refresh manually.
+original request when it receives a `401 INVALID_TOKEN` response.
 
 ## Database flow
 
 The `database` module is a thin wrapper around
-[`@supabase/postgrest-js`](https://github.com/supabase/postgrest-js)
-configured with a custom fetch that rewrites every outgoing URL:
-
-- `http://dummy/{table}?…` → `{baseUrl}/api/database/records/{table}?…`
-- `http://dummy/rpc/{fn}?…` → `{baseUrl}/api/database/rpc/{fn}?…`
-
-These paths hit the MITWAY-BaaS backend, which then proxies the request
-internally to the per-cliente PostgREST Pod (`mitway-baas-{client}-postgrest:3000`)
-over the cluster network. PostgREST verifies the JWT with the shared
-tenant `JWT_SECRET` and enforces RLS based on the role claim.
-
-The full
-[PostgREST query builder API](https://supabase.com/docs/reference/javascript/select)
-is available: `select`, `insert`, `update`, `upsert`, `delete`, `rpc`,
-filters (`.eq`, `.neq`, `.gt`, `.like`, `.in`, …), modifiers (`.order`,
-`.limit`, `.range`, `.single`, …), foreign-key joins
-(`select('*, author:users(*)')`).
+[`@supabase/postgrest-js`](https://github.com/supabase/postgrest-js).
+The full PostgREST query builder API is available: `select`, `insert`, `update`,
+`upsert`, `delete`, `rpc`, filters, modifiers, and foreign-key joins.
 
-Authorization is read from the `TokenManager` on every request, so a
-sign-in/sign-out is picked up automatically — no need to recreate the client.
+Authorization is read from the `TokenManager` on every request, so a sign-in/sign-out
+is picked up automatically.
 
 ## Origin
 
 Forked structurally from
 [`InsForge/InsForge-sdk-js`](https://github.com/InsForge/InsForge-sdk-js).
 Kept the `lib/` infrastructure (http-client, token-manager, logger)
-almost verbatim with rebranding. Rewrote `auth` for the MITWAY-BaaS
-routes and `database` to use the same fetch-rewriting pattern as
-upstream — both hit a backend proxy that forwards to the internal
-PostgREST, collapsing the per-cliente public surface into a single URL.
+with rebranding. Rewrote `auth` and `database` for the MITWAY-BaaS routes.