@emmanuel-nike/ark-notify-js 0.1.0 → 0.1.2

package/README.md

@@ -18,11 +18,18 @@ For React apps, `react` 18+ is a peer dependency.
 Wrap your app with the provider, connect a WebSocket client, and subscribe to a channel:
 
 ```tsx
-import { ArkNotifyProvider, useConnection, useChannel } from 'ark-notify-js/react'
+import {
+  configureArkNotify,
+  ArkNotifyProvider,
+  useConnection,
+  useChannel,
+} from 'ark-notify-js/react'
+
+configureArkNotify({ baseUrl: 'https://my-instance.ark-notify.com' })
 
 function App() {
   return (
-    <ArkNotifyProvider baseUrl="http://localhost:3000">
+    <ArkNotifyProvider>
       <Chat />
     </ArkNotifyProvider>
   )
@@ -43,9 +50,7 @@ function Chat() {
   return (
     <div>
       <p>Status: {state}</p>
-      <button onClick={() => publish('message', { text: 'Hello!' })}>
-        Send
-      </button>
+      <button onClick={() => publish('message', { text: 'Hello!' })}>Send</button>
     </div>
   )
 }
@@ -55,26 +60,31 @@ function Chat() {
 
 Ark Notify has two API planes:
 
-| Plane | Purpose | Auth |
-|-------|---------|------|
-| **Control** | Login, manage applications | JWT (`Authorization: Bearer`) |
-| **Data** | WebSocket/SSE clients, server-side publish | `clientId` / connection token (clients) or app key + secret (servers) |
+
+| Plane       | Purpose                                    | Auth                                                                  |
+| ----------- | ------------------------------------------ | --------------------------------------------------------------------- |
+| **Control** | Login, manage applications                 | JWT (`Authorization: Bearer`)                                         |
+| **Data**    | WebSocket/SSE clients, server-side publish | `clientId` / connection token (clients) or app key + secret (servers) |
+
 
 **Never expose your app `secret` in browser code.** Issue connection tokens and private-channel auth from your backend.
 
 ## Provider
 
+`baseUrl` is optional. Omit it to use the built-in default, or set a custom default once with `configureArkNotify()`:
+
 ```tsx
-import { ArkNotifyProvider } from 'ark-notify-js/react'
+import { configureArkNotify, ArkNotifyProvider } from 'ark-notify-js/react'
 
-<ArkNotifyProvider
-  baseUrl="https://notify.example.com"
-  token={platformJwt} // optional — for admin dashboards
->
+configureArkNotify({ baseUrl: 'https://my-instance.ark-notify.com' })
+
+<ArkNotifyProvider token={platformJwt}>
   {children}
 </ArkNotifyProvider>
 ```
 
+You can still pass `baseUrl` on the provider to override the default for that subtree.
+
 ## Platform auth (control plane)
 
 For admin dashboards that manage applications:
@@ -87,11 +97,7 @@ function Dashboard() {
   const { apps, create, remove } = useApplications()
 
   if (!isAuthenticated) {
-    return (
-      <button onClick={() => login({ email: '...', password: '...' })}>
-        Log in
-      </button>
-    )
+    return <button onClick={() => login({ email: '...', password: '...' })}>Log in</button>
   }
 
   return (
@@ -99,7 +105,9 @@ function Dashboard() {
       <p>Hello, {user?.firstName}</p>
       <button onClick={() => create({ name: 'My App' })}>New app</button>
       {apps.map((app) => (
-        <div key={app.id}>{app.name} — {app.appKey}</div>
+        <div key={app.id}>
+          {app.name} — {app.appKey}
+        </div>
       ))}
     </div>
   )
@@ -115,7 +123,7 @@ import { useConnection } from 'ark-notify-js/react'
 
 const {
   connection,
-  state,           // 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed'
+  state, // 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed'
   connectionId,
   clientId,
   authenticated,
@@ -123,8 +131,8 @@ const {
   disconnect,
 } = useConnection({
   appKey: 'app_abc',
-  clientId: 'user-42',           // when requireClientAuth is false
-  token: 'app_abc.payload.sig',  // recommended — from your backend
+  clientId: 'user-42', // when requireClientAuth is false
+  token: 'app_abc.payload.sig', // recommended — from your backend
   autoReconnect: true,
   onPrivateChannelAuth: async (channel, connectionId) => {
     const res = await fetch('/api/channel-auth', {
@@ -197,29 +205,38 @@ import {
 } from 'ark-notify-js'
 
 // REST client
-const client = new ArkNotifyClient({ baseUrl: 'http://localhost:3000' })
+const client = new ArkNotifyClient()
 await client.login({ email, password })
 const { app } = await client.createApplication({ name: 'My App' })
 
 // Server-side publish (use app credentials — never in browser)
-await client.publishEvent(app.appKey, { appKey, secret }, {
-  channel: 'room-1',
-  event: 'order.created',
-  data: { id: 123 },
-})
+await client.publishEvent(
+  app.appKey,
+  { appKey, secret },
+  {
+    channel: 'room-1',
+    event: 'order.created',
+    data: { id: 123 },
+  }
+)
 
-// Fetch a connection token (server-side)
+// Fetch a connection token (backend — requires app secret when no serverAuthUrl)
 const { token } = await fetchConnectionToken({
-  baseUrl: 'http://localhost:3000',
   appKey: app.appKey,
   credentials: { appKey: app.appKey, secret: app.secret! },
   client_id: 'user-42',
   user_data: { name: 'Alice' },
 })
 
+// Frontend — when the application has a serverAuthUrl configured
+const { token: frontendToken } = await fetchConnectionToken({
+  appKey: 'app_abc',
+  client_id: 'user-42',
+  user_data: { name: 'Alice' },
+})
+
 // WebSocket — pass token directly
 const conn = new ArkNotifyConnection({
-  baseUrl: 'http://localhost:3000',
   appKey: 'app_abc',
   token,
 })
@@ -227,7 +244,6 @@ await conn.connect()
 
 // WebSocket — auto-fetch token when credentials + clientId are provided (server-side)
 const autoConn = new ArkNotifyConnection({
-  baseUrl: 'http://localhost:3000',
   appKey: app.appKey,
   clientId: 'user-42',
   credentials: { appKey: app.appKey, secret: app.secret! },
@@ -240,37 +256,79 @@ await autoConn.subscribe('private-room-1', { auth: 'app_abc:...' })
 autoConn.publish('room-1', 'message', { text: 'hi' })
 ```
 
-When `token` is omitted, `ArkNotifyConnection` automatically calls `POST /api/v1/apps/:appKey/connection-token` if both `clientId` and `credentials` are set. On reconnect, a fresh token is fetched.
+When `token` is omitted, `ArkNotifyConnection` automatically calls `POST /api/v1/apps/:appKey/connection-token` when `clientId` is set. Pass `credentials` for backend-only apps, or omit them when the application has a `serverAuthUrl` (frontend-safe). On reconnect, a fresh token is fetched.
 
-## System admin
+## Server auth URL webhook
 
-```tsx
-import { useAdminChannels } from 'ark-notify-js/react'
+When your application has a `serverAuthUrl`, Ark Notify POSTs to it before issuing a connection token. Use `@emmanuel-nike/ark-notify-js/server` in your backend handler:
+
+```ts
+import {
+  handleServerAuth,
+  parseServerAuthRequest,
+} from '@emmanuel-nike/ark-notify-js/server'
+
+app.post('/api/ark/connection-auth', async (req, res) => {
+  const request = parseServerAuthRequest(req.body)
+  if (!request) {
+    return res.status(400).json({ allowed: false })
+  }
 
-const { data, loading, refresh } = useAdminChannels()
-// Requires SYSTEM_ADMIN JWT via ArkNotifyProvider token
+  const user = await getUserFromSession(req)
+  if (!user) {
+    return res.status(401).json({ allowed: false })
+  }
+
+  const response = await handleServerAuth({
+    request,
+    isAuthorized: () => ({
+      clientId: user.id,
+      capabilities: { publish: false },
+    }),
+  })
+
+  if ('token' in response || response.allowed === true) {
+    return res.json(response)
+  }
+
+  return res.status(403).json(response)
+})
 ```
 
+To return a pre-signed token instead (option B), pass app credentials:
+
+```ts
+const response = await handleServerAuth({
+  request,
+  isAuthorized: () => true,
+  credentials: { appKey: process.env.ARK_APP_KEY!, secret: process.env.ARK_APP_SECRET! },
+})
+// => { token: "app_abc.<payload>.<signature>" }
+```
+
+Or build a response directly with `createAuthorizedServerAuthResponse()`.
+
 ## API coverage
 
-| Feature | Hook / Class | Method |
-|---------|--------------|--------|
-| Health | `ArkNotifyClient` | `.health()` |
-| Login / me | `usePlatformAuth`, `ArkNotifyClient` | `.login()`, `.me()` |
-| Application CRUD | `useApplications`, `ArkNotifyClient` | `.listApplications()`, `.createApplication()`, … |
-| Regenerate secret | `useApplications` | `.regenerateSecret()` |
-| Admin channels | `useAdminChannels` | `.adminChannels()` |
-| Publish (server) | `ArkNotifyClient` | `.publishEvent()` |
-| Channel auth (server) | `ArkNotifyClient` | `.authorizeChannel()` |
+
+| Feature                   | Hook / Class                              | Method                                              |
+| ------------------------- | ----------------------------------------- | --------------------------------------------------- |
+| Health                    | `ArkNotifyClient`                         | `.health()`                                         |
+| Login / me                | `usePlatformAuth`, `ArkNotifyClient`      | `.login()`, `.me()`                                 |
+| Application CRUD          | `useApplications`, `ArkNotifyClient`      | `.listApplications()`, `.createApplication()`, …    |
+| Regenerate secret         | `useApplications`                         | `.regenerateSecret()`                               |
+| Publish (server)          | `ArkNotifyClient`                         | `.publishEvent()`                                   |
+| Channel auth (server)     | `ArkNotifyClient`                         | `.authorizeChannel()`                               |
 | Connection token (server) | `ArkNotifyClient`, `fetchConnectionToken` | `.issueConnectionToken()`, `fetchConnectionToken()` |
-| WebSocket connect | `useConnection`, `ArkNotifyConnection` | `.connect()` |
-| Subscribe / unsubscribe | `useChannel`, `ArkNotifyConnection` | `.subscribe()`, `.unsubscribe()` |
-| Publish (client) | `useChannel`, `ArkNotifyConnection` | `.publish()` |
-| Presence | `usePresence`, `ArkNotifyConnection` | `.presenceEnter()`, `.presenceUpdate()`, … |
-| SSE stream | `useSSE`, `ArkNotifySSE` | `.connect()` |
-| Private channels | `onPrivateChannelAuth` callback | — |
-| Auto-reconnect | `useConnection` | `autoReconnect: true` |
-| Heartbeat | `ArkNotifyConnection` | Server ping auto-replied |
+| WebSocket connect         | `useConnection`, `ArkNotifyConnection`    | `.connect()`                                        |
+| Subscribe / unsubscribe   | `useChannel`, `ArkNotifyConnection`       | `.subscribe()`, `.unsubscribe()`                    |
+| Publish (client)          | `useChannel`, `ArkNotifyConnection`       | `.publish()`                                        |
+| Presence                  | `usePresence`, `ArkNotifyConnection`      | `.presenceEnter()`, `.presenceUpdate()`, …          |
+| SSE stream                | `useSSE`, `ArkNotifySSE`                  | `.connect()`                                        |
+| Private channels          | `onPrivateChannelAuth` callback           | —                                                   |
+| Auto-reconnect            | `useConnection`                           | `autoReconnect: true`                               |
+| Heartbeat                 | `ArkNotifyConnection`                     | Server ping auto-replied                            |
+
 
 ## Error handling
 
@@ -292,4 +350,4 @@ WebSocket errors are emitted via `connection.on('error', …)` or the `useConnec
 
 ## License
 
-MIT
+MIT

package/dist/index.cjs

@@ -35,6 +35,85 @@ function isPrivateChannel(channel) {
   return channel.startsWith("private-");
 }
 
+// src/connection-token.ts
+function requiresAppSecret(options) {
+  if ("serverAuthUrl" in options) {
+    const value = options.serverAuthUrl;
+    return value === null || value === "";
+  }
+  if ("server_auth_url" in options) {
+    const value = options.server_auth_url;
+    return value === null || value === "";
+  }
+  return false;
+}
+function buildConnectionTokenRequest(options) {
+  const {
+    baseUrl,
+    appKey,
+    credentials,
+    client_id,
+    clientId,
+    user_data,
+    userData,
+    ttl,
+    capabilities,
+    serverAuthUrl,
+    server_auth_url
+  } = options;
+  const resolvedClientId = client_id ?? clientId;
+  if (!resolvedClientId) {
+    throw new Error("client_id is required to fetch a connection token");
+  }
+  if (requiresAppSecret(options) && !credentials) {
+    throw new Error(
+      "credentials are required when serverAuthUrl is explicitly set to null"
+    );
+  }
+  const body = {
+    client_id: resolvedClientId,
+    user_data: user_data ?? userData,
+    ttl,
+    capabilities
+  };
+  if ("serverAuthUrl" in options) {
+    body.serverAuthUrl = serverAuthUrl;
+  } else if ("server_auth_url" in options) {
+    body.server_auth_url = server_auth_url;
+  }
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (credentials) {
+    headers["X-App-Key"] = credentials.appKey;
+    headers["X-App-Secret"] = credentials.secret;
+  }
+  return {
+    url: `${resolveBaseUrl(baseUrl)}/api/v1/apps/${appKey}/connection-token`,
+    headers,
+    body
+  };
+}
+async function fetchConnectionToken(options) {
+  const { fetch: fetchFn = globalThis.fetch.bind(globalThis) } = options;
+  const { url, headers, body } = buildConnectionTokenRequest(options);
+  const response = await fetchFn(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) {
+    let errorBody;
+    try {
+      errorBody = await response.json();
+    } catch {
+      errorBody = { error: "request_failed", message: response.statusText };
+    }
+    throw new ArkNotifyError(response.status, errorBody);
+  }
+  return response.json();
+}
+
 // src/client.ts
 var ArkNotifyClient = class {
   constructor(config) {
@@ -113,10 +192,6 @@ var ArkNotifyClient = class {
       method: "POST"
     });
   }
-  // ── System admin ────────────────────────────────────────────────────────
-  adminChannels() {
-    return this.request("/api/v1/admin/channels");
-  }
   // ── Data plane ──────────────────────────────────────────────────────────
   publishEvent(appKey, credentials, input) {
     return this.request(`/api/v1/apps/${appKey}/events`, {
@@ -132,63 +207,17 @@ var ArkNotifyClient = class {
       credentials
     });
   }
-  issueConnectionToken(appKey, credentials, input) {
-    return this.request(`/api/v1/apps/${appKey}/connection-token`, {
-      method: "POST",
-      body: input,
-      credentials
+  issueConnectionToken(appKey, input, credentials) {
+    return fetchConnectionToken({
+      baseUrl: this.baseUrl,
+      appKey,
+      credentials,
+      ...input,
+      fetch: this.fetchFn
     });
   }
 };
 
-// src/connection-token.ts
-async function fetchConnectionToken(options) {
-  const {
-    baseUrl,
-    appKey,
-    credentials,
-    fetch: fetchFn = globalThis.fetch.bind(globalThis),
-    client_id,
-    clientId,
-    user_data,
-    userData,
-    ttl,
-    capabilities,
-    serverAuthUrl
-  } = options;
-  const resolvedClientId = client_id ?? clientId;
-  if (!resolvedClientId) {
-    throw new Error("client_id is required to fetch a connection token");
-  }
-  const body = {
-    client_id: resolvedClientId,
-    user_data: user_data ?? userData,
-    ttl,
-    capabilities,
-    serverAuthUrl
-  };
-  const url = `${resolveBaseUrl(baseUrl)}/api/v1/apps/${appKey}/connection-token`;
-  const response = await fetchFn(url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "X-App-Key": credentials.appKey,
-      "X-App-Secret": credentials.secret
-    },
-    body: JSON.stringify(body)
-  });
-  if (!response.ok) {
-    let errorBody;
-    try {
-      errorBody = await response.json();
-    } catch {
-      errorBody = { error: "request_failed", message: response.statusText };
-    }
-    throw new ArkNotifyError(response.status, errorBody);
-  }
-  return response.json();
-}
-
 // src/connection.ts
 var ArkNotifyConnection = class {
   constructor(config) {
@@ -269,13 +298,14 @@ var ArkNotifyConnection = class {
       toWebSocketUrl(this.config.baseUrl, `/app/${this.config.appKey}`)
     );
     let token = resolveValue(this.config.token);
-    if (!token && this.config.clientId && this.config.credentials) {
+    if (!token && this.config.clientId) {
       const result = await fetchConnectionToken({
         baseUrl: this.config.baseUrl,
         appKey: this.config.appKey,
         credentials: this.config.credentials,
         client_id: this.config.clientId,
         user_data: this.config.user_data,
+        serverAuthUrl: this.config.serverAuthUrl,
         fetch: this.config.fetch
       });
       token = result.token;