@productcraft/waitlist 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProductCraft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# @productcraft/waitlist
+
+Typed Node.js SDK for [ProductCraft Waitlist](https://productcraft.co) — waitlist management: public-form signups, variants for A/B/n landing pages, referrals, position + leaderboard, approval workflow with invite-to-app, signed outbound webhooks, CSV export.
+
+```bash
+npm install @productcraft/waitlist
+```
+
+The waitlist-entries endpoint can be called unauthenticated from a marketing-site form. Every other endpoint (admin, approval, analytics, exports, webhooks) requires a PlatformUser cookie or a workspace-scoped PAK (`pcft_live_…`).
+
+## Quick start — accept a signup from a public form
+
+```ts
+import { Waitlist } from "@productcraft/waitlist";
+
+// No auth — public surface
+const waitlist = new Waitlist();
+
+const { data, error } = await waitlist.client.POST(
+  "/v1/waitlists/{workspace_slug}/{waitlist_slug}/entries",
+  {
+    params: { path: { workspace_slug: "acme", waitlist_slug: "early-access" } },
+    body: {
+      email: "alice@example.com",
+      name: "Alice",
+      referrer: "twitter",
+      referral_code: "ada-123",     // optional — bumps the referrer's position
+      metadata: { plan_interest: "pro" },
+    },
+  },
+);
+```
+
+The response includes the entry's id + assigned position. Round-trip the `id` into your "thanks" page so the visitor can share their own referral link.
+
+If the waitlist has `settings.recaptcha_site_key` set, also pass a `recaptcha_token` from your client side.
+
+## Quick start — workspace-admin (authenticated)
+
+```ts
+import { Waitlist } from "@productcraft/waitlist";
+
+const waitlist = new Waitlist({
+  auth: { type: "apiKey", key: process.env.PCFT_KEY! },
+});
+
+// Create a waitlist — body uses `display_name`, not `name`.
+const { data } = await waitlist.client.POST(
+  "/v1/workspaces/{workspace_id}/waitlists",
+  {
+    params: { path: { workspace_id: "<workspace-uuid>" } },
+    body: { display_name: "Early Access", slug: "early-access" },
+  },
+);
+```
+
+`{workspace_id}` is the workspace UUID returned by `@productcraft/platform-auth`'s introspect endpoint.
+
+## Configuration
+
+```ts
+new Waitlist({
+  // Optional: required for workspace-admin calls. Public submit works without auth.
+  auth: { type: "apiKey", key: "pcft_live_..." }
+      | { type: "bearer", token: "eyJ..." }
+      | { type: "cookie", value: "auth_token=..." },
+  baseUrl: "https://api.waitlist.example.test",   // optional override
+  fetch: customFetch,                            // optional
+});
+```
+
+## Common operations
+
+### Public surface
+
+```ts
+// Read the waitlist's public metadata (name, position-window, active variant, ...)
+await waitlist.client.GET(
+  "/v1/waitlists/{workspace_slug}/{waitlist_slug}",
+  { params: { ... } },
+);
+
+// Read the public leaderboard (when enabled per-waitlist)
+await waitlist.client.GET(
+  "/v1/waitlists/{workspace_slug}/{waitlist_slug}/leaderboard",
+  { params: { ... } },
+);
+```
+
+### Entries (workspace-admin)
+
+```ts
+// List entries
+await waitlist.client.GET(
+  "/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries",
+  { params: { path: { workspace_id, waitlist_id }, query: { limit: 50 } } },
+);
+
+// Count
+await waitlist.client.GET(
+  "/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/count",
+  { ... },
+);
+
+// Approve / reject in bulk
+await waitlist.client.POST(
+  "/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/bulk",
+  { params: { ... }, body: { ids: [...], action: "approve" } },
+);
+
+// Send an invite (e.g. into an Auth app)
+await waitlist.client.POST(
+  "/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/{entry_id}/invite-to-app",
+  { params: { ... }, body: { /* app + role + invite_template */ } },
+);
+
+// Export to CSV
+await waitlist.client.GET(
+  "/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/entries/export.csv",
+  { ... },
+);
+```
+
+### Variants (A/B/n landing pages)
+
+Variants split two ways: `kind: "ab"` for split-traffic A/B/n tests, or `kind: "locale"` for per-locale copy switching. Pick one; the body shape is `{ kind, slug, locale? }`.
+
+```ts
+// A/B variant
+await waitlist.client.POST(
+  "/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/variants",
+  {
+    params: { ... },
+    body: { kind: "ab", slug: "headline-b" },
+  },
+);
+
+// Locale variant
+await waitlist.client.POST(
+  "/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/variants",
+  {
+    params: { ... },
+    body: { kind: "locale", slug: "pt-br", locale: "pt-BR" },
+  },
+);
+```
+
+Front-end picks up the active variant from `GET /v1/waitlists/:workspace_slug/:waitlist_slug` and round-trips its id back in the entry submission via the `variant_id` field — Waitlist computes per-variant conversion without a separate impressions table.
+
+### Analytics
+
+```ts
+// Conversion + per-variant counts
+await waitlist.client.GET(
+  "/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/analytics",
+  { ... },
+);
+
+// Timeseries — `since` is an ISO-8601 timestamp. There are no
+// `bucket` / `lookback` query params.
+await waitlist.client.GET(
+  "/v1/workspaces/{workspace_id}/waitlists/{waitlist_id}/analytics/timeline",
+  {
+    params: {
+      path: { ... },
+      query: { since: "2026-05-01T00:00:00Z" },
+    },
+  },
+);
+```
+
+### Webhooks
+
+```ts
+// Subscribe to entry.created / entry.approved / entry.rejected
+await waitlist.client.POST(
+  "/v1/workspaces/{workspace_id}/webhooks",
+  { params: { ... }, body: { url: "https://yourapp.com/hooks/waitlist", events: ["entry.created"] } },
+);
+
+// Rotate the signing secret without disabling the webhook
+await waitlist.client.POST(
+  "/v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secret",
+  { ... },
+);
+
+// Replay a delivery from history
+await waitlist.client.GET(
+  "/v1/workspaces/{workspace_id}/webhooks/{id}/deliveries",
+  { ... },
+);
+```
+
+## How this SDK is built
+
+Generated from the live OpenAPI spec at `https://api.waitlist.productcraft.co/docs-json` via [`openapi-typescript`](https://openapi-ts.dev/) + [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/). The nightly `spec-refresh` workflow opens a PR whenever the spec changes.
+
+## License
+
+[MIT](https://github.com/clauderanelagh/productcraft-node/blob/main/LICENSE).

package/dist/index.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var core = require('@productcraft/core');
+
+// src/index.ts
+var Waitlist = class {
+  /** The underlying typed client. v0 surface — every endpoint reachable. */
+  client;
+  constructor(config = {}) {
+    this.client = core.makeClient(core.PC_BASE_URL.waitlist, config);
+  }
+};
+
+exports.Waitlist = Waitlist;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["makeClient","PC_BASE_URL"],"mappings":";;;;;AASO,IAAM,WAAN,MAAe;AAAA;AAAA,EAEJ,MAAA;AAAA,EAEhB,WAAA,CAAY,MAAA,GAAyB,EAAC,EAAG;AACvC,IAAA,IAAA,CAAK,MAAA,GAASA,eAAA,CAAkBC,gBAAA,CAAY,QAAA,EAAU,MAAM,CAAA;AAAA,EAC9D;AACF","file":"index.cjs","sourcesContent":["import type { paths } from \"./_generated.js\";\nimport { makeClient, PC_BASE_URL, type PCClientConfig } from \"@productcraft/core\";\n\n/**\n * Waitlist — typed `openapi-fetch` client for every endpoint in\n * `Specs/waitlist.json`. Reach for `client.GET(\"/v1/...\")` or\n * `client.POST(...)`; request / response types come from the\n * generated `paths` interface.\n */\nexport class Waitlist {\n  /** The underlying typed client. v0 surface — every endpoint reachable. */\n  public readonly client: ReturnType<typeof makeClient<paths>>;\n\n  constructor(config: PCClientConfig = {}) {\n    this.client = makeClient<paths>(PC_BASE_URL.waitlist, config);\n  }\n}\n\nexport type { paths } from \"./_generated.js\";\n"]}