{"_id":"@callowayisweird/supersaas","_rev":"2-37c6288d81d858e0baf4db0f8628b2bb","name":"@callowayisweird/supersaas","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@callowayisweird/supersaas","version":"1.0.0","keywords":["supersaas","booking","scheduling","appointments","typescript","sdk"],"author":{"name":"CallowayIsWeird"},"license":"MIT","_id":"@callowayisweird/supersaas@1.0.0","maintainers":[{"name":"callowayisweird","email":"henrythegamerguy62@gmail.com"}],"homepage":"https://github.com/CallowayIsWeird/supersaas-api#readme","bugs":{"url":"https://github.com/CallowayIsWeird/supersaas-api/issues"},"dist":{"shasum":"518e8fb1aeb1baede3995e4bf2aee7ef3f2668a7","tarball":"https://registry.npmjs.org/@callowayisweird/supersaas/-/supersaas-1.0.0.tgz","fileCount":10,"integrity":"sha512-ADemHGk0Sz553D4VgMaUCliETGXpeX3RSovsXO0gsBDIVGGQng5RKLCbQrWJ5l8W5hPQVDjfaOR8SrPtq14G6g==","signatures":[{"sig":"MEUCICzHrNHTXTRzXzGHIex+GS+ji0acjvod68wtJ4A33cc5AiEA30B9xRBm6786Jo61mC8gRpJBw3oc+v3P+/0z02jyyTo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@callowayisweird%2fsupersaas@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":358368},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"gitHead":"e3e1b07face563c1db2dfba9ed37a3cbe0b69f2d","scripts":{"docs":"typedoc","lint":"eslint .","test":"vitest run","build":"tsup","format":"prettier --write .","release":"npm run prepublishOnly && npm publish --access public","lint:fix":"eslint . --fix","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check .","test:coverage":"vitest run --coverage","prepublishOnly":"npm run typecheck && npm run lint && npm run test && npm run build"},"_npmUser":{"name":"callowayisweird","email":"henrythegamerguy62@gmail.com"},"repository":{"url":"git+https://github.com/CallowayIsWeird/supersaas-api.git","type":"git"},"_npmVersion":"10.9.7","description":"Modern, fully-typed TypeScript SDK for the SuperSaaS booking platform.","directories":{},"sideEffects":false,"_nodeVersion":"22.22.2","publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","eslint":"^9.17.0","vitest":"^2.1.8","typedoc":"^0.27.5","prettier":"^3.4.2","typescript":"^5.7.2","@types/node":"^22.10.0","@vitest/coverage-v8":"^2.1.8","eslint-config-prettier":"^9.1.0","@typescript-eslint/parser":"^8.18.0","@typescript-eslint/eslint-plugin":"^8.18.0"},"_npmOperationalInternal":{"tmp":"tmp/supersaas_1.0.0_1777341391206_0.8430215632112585","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@callowayisweird/supersaas","version":"1.0.1","description":"Modern, fully-typed TypeScript SDK for the SuperSaaS booking platform.","keywords":["supersaas","booking","scheduling","appointments","typescript","sdk"],"license":"MIT","author":{"name":"CallowayIsWeird"},"homepage":"https://github.com/CallowayIsWeird/supersaas-api#readme","repository":{"type":"git","url":"git+https://github.com/CallowayIsWeird/supersaas-api.git"},"bugs":{"url":"https://github.com/CallowayIsWeird/supersaas-api/issues"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"engines":{"node":">=22"},"sideEffects":false,"scripts":{"build":"tsup","typecheck":"tsc --noEmit","lint":"eslint .","lint:fix":"eslint . --fix","format":"prettier --write .","format:check":"prettier --check .","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","docs":"typedoc","prepublishOnly":"npm run typecheck && npm run lint && npm run test && npm run build","release":"npm run prepublishOnly && npm publish --access public"},"devDependencies":{"@types/node":"^22.10.0","@typescript-eslint/eslint-plugin":"^8.18.0","@typescript-eslint/parser":"^8.18.0","@vitest/coverage-v8":"^2.1.8","eslint":"^9.17.0","eslint-config-prettier":"^9.1.0","prettier":"^3.4.2","tsup":"^8.3.5","typedoc":"^0.27.5","typescript":"^5.7.2","vitest":"^2.1.8"},"publishConfig":{"access":"public","provenance":true},"_id":"@callowayisweird/supersaas@1.0.1","gitHead":"42dbfb5efd81ac6aedb1c6f4d119b46c6be29ebd","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-mMHFKhQ5nusWzDFpnonTSOIA5pu+GZ6Zj7godjq5SE/NQRZMDk4XGyymAHBNh8K9e9tjUxs09YAUezxSB5ic5g==","shasum":"b2107a61f6587be2afb76c01ecd51c0dd9b4d2b5","tarball":"https://registry.npmjs.org/@callowayisweird/supersaas/-/supersaas-1.0.1.tgz","fileCount":10,"unpackedSize":361584,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@callowayisweird%2fsupersaas@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAKa6taPbw02PPvxHeWaCIBQCZ3OTO+OjrKL/WplVhbhAiAhRQ5yKdF/NblgpXONeYIyfgiM/4bv8UXTuQKrxhJEmw=="}]},"_npmUser":{"name":"callowayisweird","email":"henrythegamerguy62@gmail.com"},"directories":{},"maintainers":[{"name":"callowayisweird","email":"henrythegamerguy62@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/supersaas_1.0.1_1783223248191_0.8631333286339973"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-28T01:56:31.080Z","modified":"2026-07-05T03:47:28.613Z","1.0.0":"2026-04-28T01:56:31.367Z","1.0.1":"2026-07-05T03:47:28.342Z"},"bugs":{"url":"https://github.com/CallowayIsWeird/supersaas-api/issues"},"author":{"name":"CallowayIsWeird"},"license":"MIT","homepage":"https://github.com/CallowayIsWeird/supersaas-api#readme","keywords":["supersaas","booking","scheduling","appointments","typescript","sdk"],"repository":{"type":"git","url":"git+https://github.com/CallowayIsWeird/supersaas-api.git"},"description":"Modern, fully-typed TypeScript SDK for the SuperSaaS booking platform.","maintainers":[{"name":"callowayisweird","email":"henrythegamerguy62@gmail.com"}],"readme":"# @callowayisweird/supersaas\n\n[![npm version](https://img.shields.io/npm/v/@callowayisweird/supersaas.svg)](https://www.npmjs.com/package/@callowayisweird/supersaas)\n[![ci](https://github.com/CallowayIsWeird/supersaas-api/actions/workflows/ci.yml/badge.svg)](https://github.com/CallowayIsWeird/supersaas-api/actions/workflows/ci.yml)\n[![license](https://img.shields.io/npm/l/@callowayisweird/supersaas.svg)](LICENSE)\n\nModern, fully-typed TypeScript SDK for the [SuperSaaS](https://www.supersaas.com) booking platform.\n\nThis library is a ground-up TypeScript rewrite of the [official SuperSaaS Node.js client](https://github.com/SuperSaaS/supersaas-nodejs-api-client) with strict typing, structured errors, real concurrency-safe rate limiting, retries with exponential backoff, request timeouts, async-iterator pagination, and a pluggable HTTP layer. Drop-in for any modern Node project.\n\n---\n\n## Install\n\n```bash\nnpm install @callowayisweird/supersaas\n```\n\nRequires **Node ≥ 22**.\n\n## Quickstart\n\n```ts\nimport { SuperSaas } from '@callowayisweird/supersaas';\n\nconst client = new SuperSaas({\n  accountName: 'your-account-name',\n  apiKey: process.env.SSS_API_KEY!,\n  timezone: 'America/New_York', // your schedules' configured timezone\n});\n\nconst schedules = await client.schedules.list();\nconsole.log(schedules);\n```\n\nOr build from environment variables (`SSS_API_ACCOUNT_NAME` and `SSS_API_KEY`):\n\n```ts\nconst client = SuperSaas.fromEnv({ timezone: 'America/New_York' });\n```\n\n## Why this library\n\nThe upstream `supersaas-api-client` package works but has several real issues:\n\n| Upstream | This library |\n|---|---|\n| No TypeScript types — everything is `any` | Strict TS end-to-end, full inference at call sites |\n| Methods take both Promise and Node-style callback (footgun) | Promise-only |\n| Errors are bare `Error` with status-only message | Typed error hierarchy with status, path, method, body, requestId |\n| Throttle is broken under concurrency (parallel calls all pass) | Real async-mutex queue, honors `Retry-After` |\n| No request timeout | Configurable per-request timeout via `AbortSignal` |\n| No retries on 5xx or transient errors | Exponential-backoff retry for idempotent + 5xx |\n| `new Buffer.from(...)` (deprecated) | Modern `Buffer.from(...)` |\n| Module-level singleton reads env at import time | Class-based, explicit instantiation |\n| Datetime formatter uses local-machine TZ silently | Explicit IANA timezone, `Intl`-based |\n| Magic numeric roles `[3, 4, -1]` | Named `Role.Customer`, `Role.Admin`, `Role.Restricted` |\n| 10-arg positional method signatures | Options-object signatures |\n| Manual limit/offset pagination | `for await` async iterators |\n| `console.log` baked into library | Pluggable `Logger` interface (default: silent) |\n| `Appointments.agenda` returns malformed result | Returns array of typed results |\n| `dryRun` half-implemented | Test by injecting your own `HttpClient` |\n| CommonJS only | Dual ESM + CJS, tree-shakeable |\n\n## API surface\n\n### Client\n\n```ts\nconst client = new SuperSaas({\n  accountName: string,           // required\n  apiKey: string,                // required\n  host?: string,                 // default: https://www.supersaas.com\n  timezone?: string,             // default: 'UTC'\n  timeout?: number,              // default: 30_000 (ms)\n  maxRetries?: number,           // default: 3\n  retryBaseDelayMs?: number,     // default: 200\n  retryMaxDelayMs?: number,      // default: 30_000\n  rateLimitIntervalMs?: number,  // default: 1000 (set to 0 to disable)\n  logger?: Logger,               // default: noopLogger\n  httpClient?: HttpClient,       // default: built-in FetchHttpClient\n});\n```\n\n### Resources\n\n| Namespace | Methods |\n|---|---|\n| `client.appointments` | `list`, `get`, `create`, `update`, `delete`, `agenda`, `available`, `range`, `changes` |\n| `client.users` | `list`, `iterate`, `get`, `create`, `update`, `delete`, `fieldList` |\n| `client.schedules` | `list`, `resources`, `fieldList` |\n| `client.forms` | `list`, `get`, `templates` |\n| `client.promotions` | `list`, `get`, `duplicate` |\n| `client.groups` | `list` |\n\nEvery method returns a fully typed `Promise<T>`. Every method accepts an optional `RequestOptions` parameter for per-request `signal`, `timeout`, `maxRetries`, and `idempotencyKey`.\n\n### Pagination\n\nList endpoints return one page. To walk all results, use `iterate()`:\n\n```ts\nfor await (const user of client.users.iterate({ pageSize: 100 })) {\n  console.log(user.email);\n}\n\n// Or materialize with a cap:\nimport { collect } from '@callowayisweird/supersaas';\nconst all = await collect(client.users.iterate({ maxResults: 500 }));\n```\n\n### Errors\n\nAll errors extend `SuperSaasError` and carry context:\n\n```ts\nimport {\n  AuthError,\n  ForbiddenError,\n  NotFoundError,\n  ValidationError,\n  RateLimitError,\n  ServerError,\n  NetworkError,\n  TimeoutError,\n} from '@callowayisweird/supersaas';\n\ntry {\n  await client.appointments.create({ ... });\n} catch (err) {\n  if (err instanceof RateLimitError) {\n    await new Promise((r) => setTimeout(r, err.retryAfterMs));\n  } else if (err instanceof ValidationError) {\n    console.error(err.fieldErrors); // { field: [messages...] }\n  } else if (err instanceof NotFoundError) {\n    // ...\n  }\n}\n```\n\nErrors expose `status`, `method`, `path`, `requestId`, and `body` for production debugging.\n\n### Idempotency\n\nPass an `idempotencyKey` to make POST requests safe to retry:\n\n```ts\nawait client.appointments.create(\n  { scheduleId, userId, attributes },\n  { idempotencyKey: crypto.randomUUID() },\n);\n```\n\nWhen set, the request is automatically retried on transient failures. SuperSaaS will not double-create resources for the same key.\n\n### Custom HTTP transport\n\nInject a custom transport for testing, observability, or custom auth:\n\n```ts\nimport type { HttpClient, HttpRequest, HttpResponse } from '@callowayisweird/supersaas';\n\nclass LoggingHttpClient implements HttpClient {\n  constructor(private inner: HttpClient) {}\n  async request<T>(req: HttpRequest): Promise<HttpResponse<T>> {\n    console.time(`${req.method} ${req.path}`);\n    try {\n      return await this.inner.request<T>(req);\n    } finally {\n      console.timeEnd(`${req.method} ${req.path}`);\n    }\n  }\n}\n```\n\n## Migrating from `supersaas-api-client`\n\n```diff\n- const Client = require('supersaas-api-client');\n- Client.configure({ accountName: 'a', api_key: 'k' });\n- const slots = await Client.Instance.appointments.range(\n-   42, false, '2026-04-28 09:00:00', '2026-04-28 23:00:00',\n-   false, null, null, null, 50, 0,\n- );\n+ import { SuperSaas } from '@callowayisweird/supersaas';\n+ const client = new SuperSaas({ accountName: 'a', apiKey: 'k' });\n+ const slots = await client.appointments.range({\n+   scheduleId: 42,\n+   from: '2026-04-28 09:00:00',\n+   to: '2026-04-28 23:00:00',\n+   limit: 50,\n+ });\n```\n\nKey differences:\n\n- `api_key` → `apiKey`\n- All resource methods take an options object instead of positional args\n- `Client.Instance` singleton pattern is gone; instantiate explicitly\n- `Appointments.agenda` now returns an array (not a wrapped object)\n- Typed errors instead of `Error('Request failed with status 422')`\n\n## Configuration recipes\n\n### Client with an explicit timezone\n\n```ts\nconst client = new SuperSaas({\n  accountName: 'your-account-name',\n  apiKey: process.env.SSS_API_KEY!,\n  timezone: 'America/New_York',\n});\n```\n\n### Tight rate limiting / fast retries\n\n```ts\nconst client = new SuperSaas({\n  accountName: 'a',\n  apiKey: 'k',\n  rateLimitIntervalMs: 250,\n  retryBaseDelayMs: 100,\n  maxRetries: 5,\n});\n```\n\n### Disable rate limiting (e.g. when SuperSaaS doesn't enforce one for your tier)\n\n```ts\nconst client = new SuperSaas({\n  accountName: 'a',\n  apiKey: 'k',\n  rateLimitIntervalMs: 0,\n});\n```\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm run lint\nnpm test\nnpm run build\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\nThis library is a derivative work of the official [SuperSaaS Node.js API Client](https://github.com/SuperSaaS/supersaas-nodejs-api-client) (© 2018 SuperSaaS), also MIT.\n","readmeFilename":"README.md"}