@vuoma/sdk 0.1.0 → 0.1.1

package/README.md

@@ -4,15 +4,28 @@ Framework-neutral JavaScript and TypeScript client for the existing Vuoma v1
 public organization and member account APIs. Works with a host-provided Fetch
 implementation; it imports no React, Svelte, Expo or Supabase runtime. The package
 does not store credentials, read environment variables, create accounts, or
-grant access. This is a local package foundation; registry publication is a
-separate step.
+grant access. Install the public package and pin the reviewed version:
+
+```sh
+npm install @vuoma/sdk@0.1.1
+```
+
+Use SvelteKit and SvelteKit UI with `@vuoma/web` for website account components
+and same-origin server sessions. Use React Native for mobile UI and this SDK as
+its framework-neutral API transport. The complete `@vuoma/react-native` studio
+app core remains a private workspace; independent apps do not depend on it.
+The public setup guide is at `/developers` and `/o/<organization_slug>/developers`
+on the same combined Vuoma application and landing-page deployment. The current
+origin is `https://vuoma.vercel.app`; use `https://vuoma.com` only after domain
+cutover and exact-origin configuration have been verified.
 
 ```js
 import { createVuomaClient } from '@vuoma/sdk'
 
 const vuoma = createVuomaClient({
-  apiOrigin: 'http://localhost:5173', // Use your verified Vuoma HTTPS origin in production.
+  apiOrigin: 'https://vuoma.vercel.app', // Use your verified Vuoma origin.
   organizationSlug: 'your-studio',
+  appKey: publishableAppKey, // The organization's registered vuoma_pk_ app key.
   fetch: globalThis.fetch,
 })
 
@@ -24,7 +37,12 @@ const schedule = await vuoma.public.getSchedule({
 })
 ```
 
-No key is needed for these public reads. Schedule timestamps are normalized to
+The optional `appKey` identifies a registered organization app. Obtain its
+publishable `vuoma_pk_` key from the organization's app registration and use the
+same key for public reads, sign-in, refresh, sign-out and member requests. Public
+reads also work without an app key where the API allows anonymous access. The
+organization slug is a route hint; the server validates the app's organization
+binding. Schedule timestamps are normalized to
 UTC, and ranges must be positive and at most 63 days. The response preserves
 `schedule.has_more`; when it is true, split the requested range and fetch each
 part rather than displaying the first response as a complete schedule.
@@ -39,8 +57,9 @@ server or native host; it does not establish a browser cookie session.
 ```js
 let session = null // Example in-memory host state; no SDK persistence.
 const vuoma = createVuomaClient({
-  apiOrigin: 'http://localhost:5173',
+  apiOrigin: 'https://vuoma.vercel.app',
   organizationSlug: 'your-studio',
+  appKey: publishableAppKey,
   tokenAdapter: { getSession: () => session },
 })
 
@@ -63,6 +82,12 @@ Native, keep refresh tokens in Keychain/Keystore through a secure-storage adapte
 keep access tokens in memory, and refresh through the documented member route.
 Refresh scheduling, retries and persistence remain host responsibilities.
 
+An app-bound member session requires the same active app registration on each
+request. Revoking that registration invalidates its bound sessions. Re-enabling
+or replacing an app key does not restore those sessions: remove the rejected
+session from your host adapter and require a fresh member sign-in. The SDK does
+not retry authorization failures or silently change registrations.
+
 The SDK uses `credentials: 'omit'`, prevents redirects, and sends member access
 tokens only to its exact configured origin and organization. It rejects missing,
 expired, cross-organization, platform-account, organization API, identity-only
@@ -80,6 +105,14 @@ the response text and against a supplied Content-Length header.
 
 ## Keys and client IDs
 
+- **Publishable Vuoma app keys** have the exact format `vuoma_pk_` followed by
+  32 lowercase hexadecimal characters. They may be included in an app bundle
+  and identify its organization registration. The SDK sends them only in
+  `X-Vuoma-App-Key` to its configured origin, never in `Authorization`, a URL
+  or a request body. They do not sign a customer in or grant private access;
+  member access/refresh tokens and the server's live app/session checks remain
+  required. Confidential organization or Supabase service keys are rejected
+  as `appKey` values.
 - **Organization integration/delegated API keys** are confidential server
   credentials. Never put them in a website bundle, native binary, URL or SDK
   token adapter. They do not sign a customer in.
@@ -93,9 +126,9 @@ the response text and against a supplied Content-Length header.
   accepted by this member client.
 
 This package adds no OAuth grant, CORS policy or backend permission. A third-party
-website still needs its backend adapter. Independent app authorization and
-app-scoped member grants are separate platform work; a public app ID alone must
-never authorize private account data.
+website still needs its backend adapter. App registration and app-scoped member
+session grants are enforced by the API; a publishable app key alone never
+authorizes private account data.
 
 Supported routes are public `/api/v1/o/{slug}/member/{bootstrap,schedule,catalog}`;
 member sign-in, profile GET/PATCH and commerce GET; plus the existing global
@@ -112,6 +145,6 @@ npm run verify
 Verification tests the actual wire route/header/session boundaries and creates
 an installable npm archive under `artifacts/`. It checks the archive's public
 file list and loads the packed module in an isolated temporary directory.
-Nothing is published and no registry authentication is attempted. The inherited
+The verification command does not publish or attempt registry authentication. The inherited
 license remains `UNLICENSED`; `private: false` prepares packaging without granting
 open-source licensing rights.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vuoma/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Framework-neutral client for Vuoma public organization and member account APIs",
   "type": "module",
   "private": false,

package/src/index.d.ts

@@ -22,6 +22,8 @@ export interface VuomaClientOptions {
   organizationSlug: string
   /** Optional stronger client-side tenant check against the member JWT claim. */
   organizationId?: string
+  /** Publishable vuoma_pk_ app identity; private calls still require member auth. */
+  appKey?: string
   fetch?: typeof globalThis.fetch
   tokenAdapter?: MemberTokenAdapter
   /** Default 2 MiB; accepted range 1 KiB–16 MiB. */

package/src/index.js

@@ -1,5 +1,6 @@
 // Public package: no environment reads, provider clients, persistence or secrets.
 const slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u
+const appKeyPattern = /^vuoma_pk_[0-9a-f]{32}$/u
 const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu
 const timestampPattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/u
 const maximumRange = 63 * 24 * 60 * 60 * 1000
@@ -134,6 +135,8 @@ export function createVuomaClient(options) {
   if (typeof organizationSlug !== "string" || organizationSlug.length < 2 || organizationSlug.length > 80 || !slugPattern.test(organizationSlug)) throw new TypeError("Use an exact organization slug.")
   const organizationId = options.organizationId
   if (organizationId !== undefined && !uuid(organizationId)) throw new TypeError("Use a valid organization ID.")
+  const appKey = options.appKey
+  if (appKey !== undefined && (typeof appKey !== "string" || !appKeyPattern.test(appKey))) throw new TypeError("Use a publishable Vuoma app key.")
   const requestFetch = options.fetch ?? globalThis.fetch
   if (typeof requestFetch !== "function") throw new TypeError("A fetch implementation is required.")
   const tokenAdapter = options.tokenAdapter
@@ -151,6 +154,7 @@ export function createVuomaClient(options) {
     const url = new URL(path, origin)
     if (query) for (const [key, value] of Object.entries(query)) url.searchParams.set(key, value)
     const headers = { accept: "application/json" }
+    if (appKey !== undefined) headers["x-vuoma-app-key"] = appKey
     if (body !== undefined) headers["content-type"] = "application/json"
     if (accessToken) headers.authorization = `Bearer ${accessToken}`
     const response = await requestFetch(url.href, {