@foxscheduling/sdk 0.1.0 → 0.1.1

package/README.md

@@ -2,27 +2,105 @@
 
 Official Node.js SDK for the [Fox Scheduling Partner API](https://foxscheduling.com/developers).
 
+Use this package to read and manage bookings, customers, availability, and more on behalf of a Fox Scheduling business — from your own server or integration.
+
+**Requirements:** Node.js 18+
+
+**Full API reference:** [foxscheduling.com/developers](https://foxscheduling.com/developers)
+
+---
+
 ## Install
 
 ```bash
 npm install @foxscheduling/sdk @foxscheduling/shared
 ```
 
-## API key (single business)
+Both packages are required. `@foxscheduling/shared` provides shared types and scope names.
+
+---
+
+## Choose how to authenticate
+
+| Method | Best for | Dashboard setup |
+| --- | --- | --- |
+| **API key** | Scripts, cron jobs, or automation for **your own** Fox business | [Developers → API keys](https://foxscheduling.com/dashboard/developers?tab=api-keys) |
+| **OAuth** | SaaS apps where **other people** connect their Fox business to your product | [Developers → OAuth apps](https://foxscheduling.com/dashboard/developers) |
+
+If you only need to access a business you own, start with an **API key**. It is the fastest path.
+
+---
+
+## Quick start: API key
+
+### 1. Create a key
+
+1. Sign in to [Fox Scheduling](https://foxscheduling.com).
+2. Open **Developers → API keys**.
+3. Pick the business, choose scopes (e.g. `business:read`, `bookings:read`), and create a key.
+4. Copy the key immediately — it is shown only once. Keys look like `fx_live_...`.
+
+### 2. Call the API
 
 ```typescript
 import { FoxScheduling } from "@foxscheduling/sdk";
 
 const fox = new FoxScheduling({
-  auth: { type: "apiKey", apiKey: process.env.FOX_API_KEY! },
+  auth: {
+    type: "apiKey",
+    apiKey: process.env.FOX_API_KEY!, // fx_live_...
+  },
 });
 
+// Example: read the connected business profile
 const business = await fox.business.get();
+console.log(business.name);
+```
+
+### Available resources
+
+After creating a client, use:
+
+- `fox.business` — business profile
+- `fox.services` — services
+- `fox.staff` — staff members
+- `fox.availability` — availability rules
+- `fox.bookings` — bookings
+- `fox.customers` — customers
+- `fox.webhooks` — webhook subscriptions
+
+All methods return typed data and throw on API errors.
+
+---
+
+## OAuth: connect other users' businesses
+
+Use OAuth when you are building an integration (e.g. a CRM or reporting tool) and Fox Scheduling **users** need to authorize your app to access **their** business.
+
+OAuth is a browser-based flow. At a high level:
+
 ```
+Your app                    Fox Scheduling              User's browser
+   |                              |                            |
+   |-- 1. Build authorize URL --->|                            |
+   |-- 2. Redirect user -------------------------------------->|
+   |                              |<-- 3. User signs in & allows
+   |<-- 4. Redirect to your URL with ?code=... ---------------|
+   |-- 5. Exchange code for tokens ->|                          |
+   |-- 6. Call Partner API with stored tokens                   |
+```
+
+You never type the authorization `code` yourself. Fox appends it to your redirect URL after the user clicks **Allow**.
+
+### Before you write code
 
-Create keys under **Settings → API keys** in the Fox Scheduling dashboard.
+1. Create an OAuth app under **Developers → OAuth apps**.
+2. Note the **client ID** and **client secret** (secret is shown once).
+3. Add a **redirect URI** — the exact URL Fox will send users back to, e.g. `https://your-app.com/oauth/callback`. It must match character-for-character in your code.
 
-## OAuth (multi-tenant integrations)
+### Step 1 — Send the user to Fox
+
+Create the SDK client and build the authorization URL:
 
 ```typescript
 import { FoxScheduling, FileTokenStore } from "@foxscheduling/sdk";
@@ -32,27 +110,148 @@ const fox = new FoxScheduling({
     type: "oauth",
     clientId: process.env.FOX_CLIENT_ID!,
     clientSecret: process.env.FOX_CLIENT_SECRET!,
-    redirectUri: "https://your-domain.com/oauth/callback",
+    redirectUri: "https://your-app.com/oauth/callback", // must match dashboard
     tokenStore: new FileTokenStore("./fox-tokens.json"),
   },
 });
 
-const { url, codeVerifier } = fox.oauth!.getAuthorizationUrl({
+const { url, codeVerifier, state } = fox.oauth!.getAuthorizationUrl({
   scopes: ["business:read", "bookings:read"],
 });
-// Redirect user to url, then on callback:
-await fox.oauth!.exchangeCode(code, codeVerifier);
 ```
 
-## Webhook verification
+**Important:** Before redirecting the user, save `codeVerifier` and `state` somewhere tied to that user session (memory, Redis, database, encrypted cookie, etc.). You need them on the next step.
+
+Then redirect the user's browser to `url` (e.g. `res.redirect(url)` in Express).
+
+### Step 2 — Handle the callback
+
+When the user approves, Fox redirects to your `redirectUri` with query parameters:
+
+```
+https://your-app.com/oauth/callback?code=AUTHORIZATION_CODE&state=SAME_STATE_YOU_SAVED
+```
+
+In your callback route:
+
+1. Read `code` and `state` from the query string.
+2. Confirm `state` matches what you saved (prevents CSRF).
+3. Load the saved `codeVerifier` for that session.
+4. Exchange the code for tokens.
+
+```typescript
+// Example: Express route GET /oauth/callback
+app.get("/oauth/callback", async (req, res) => {
+  const code = req.query.code as string | undefined;
+  const returnedState = req.query.state as string | undefined;
+
+  if (!code) {
+    return res.status(400).send("Authorization was denied or failed.");
+  }
+  if (returnedState !== savedState) {
+    return res.status(400).send("Invalid state — possible CSRF.");
+  }
+
+  await fox.oauth!.exchangeCode(code, savedCodeVerifier);
+
+  // Tokens are saved automatically. Redirect to your app.
+  res.redirect("/dashboard");
+});
+```
+
+### Step 3 — Use the API
+
+Once `exchangeCode` succeeds, the SDK stores tokens and attaches them to every request. You can call the same resources as with an API key:
+
+```typescript
+const business = await fox.business.get();
+const bookings = await fox.bookings.list();
+```
+
+The SDK refreshes access tokens automatically before they expire.
+
+### What is `fox-tokens.json`?
+
+In the examples above, `FileTokenStore("./fox-tokens.json")` tells the SDK **where to save OAuth tokens on disk**.
+
+- **You do not create this file.** The SDK writes it after a successful `exchangeCode`.
+- The path is just an example — use any path you like.
+- **Keep it secret** — it contains refresh tokens. Add it to `.gitignore`.
+- **One file = one connection.** Fine for local scripts or a single test business.
+
+Example contents (written by the SDK):
+
+```json
+{
+  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
+  "refreshToken": "opaque-refresh-token",
+  "expiresAt": 1710003600000,
+  "scope": "business:read bookings:read",
+  "tokenType": "Bearer"
+}
+```
+
+### Production OAuth apps
+
+If many Fox users will connect their businesses, **do not** use one shared file. Implement the `TokenStore` interface and save tokens in your database, keyed by your user ID (or Fox `tenant_id`):
+
+```typescript
+import type { TokenStore, TokenSet } from "@foxscheduling/sdk";
+
+class DatabaseTokenStore implements TokenStore {
+  constructor(private userId: string) {}
+  async load(): Promise<TokenSet | null> { /* read from DB */ }
+  async save(tokens: TokenSet): Promise<void> { /* write to DB */ }
+  async clear(): Promise<void> { /* delete from DB */ }
+}
+```
+
+For unit tests, use `MemoryTokenStore()` (tokens disappear when the process exits).
+
+More detail: [OAuth2 integration guide](https://foxscheduling.com/developers/oauth2)
+
+---
+
+## Webhook signature verification
+
+When Fox sends a webhook to your server, verify the `X-Fox-Signature` header:
 
 ```typescript
 import { verifyFoxWebhookSignature } from "@foxscheduling/sdk";
 
 const ok = verifyFoxWebhookSignature({
-  secret: webhookSecret,
+  secret: process.env.FOX_WEBHOOK_SECRET!,
   timestamp: req.headers["x-fox-timestamp"],
-  rawBody: req.rawBody,
+  rawBody: req.rawBody, // unparsed request body string
   signatureHex: req.headers["x-fox-signature"],
 });
+
+if (!ok) {
+  return res.status(401).send("Invalid signature");
+}
 ```
+
+Your HTTP framework must give you the **raw** body (before JSON parsing) for verification to work.
+
+---
+
+## Scopes
+
+Each API key or OAuth request uses scopes such as:
+
+`business:read`, `services:read`, `staff:read`, `availability:read`, `availability:write`, `bookings:read`, `bookings:write`, `customers:read`, `customers:write`, `webhooks:read`, `webhooks:write`
+
+Request only the scopes your integration needs. See the [scope reference](https://foxscheduling.com/developers/oauth2#scopes).
+
+---
+
+## Links
+
+- [Developers hub](https://foxscheduling.com/developers)
+- [OAuth2 guide](https://foxscheduling.com/developers/oauth2)
+- [API key guide](https://foxscheduling.com/developers/api-key)
+- [Developers dashboard](https://foxscheduling.com/dashboard/developers)
+
+## Support
+
+Questions or integration help: [foxscheduling.com/contact](https://foxscheduling.com/contact)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxscheduling/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official Fox Scheduling Partner API SDK",
   "type": "module",
   "main": "./dist/cjs/index.cjs",