@nestuge/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nestuge
+
+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,203 @@
+# @nestuge/sdk
+
+Official TypeScript/JavaScript SDK for the [Nestuge](https://nestuge.com) Developer API.
+Fully typed, zero runtime dependencies, and runs anywhere `fetch` does — Node.js ≥ 18, Bun, Deno, browsers, and edge runtimes.
+
+## Installation
+
+```bash
+npm install @nestuge/sdk
+# or
+pnpm add @nestuge/sdk
+# or
+yarn add @nestuge/sdk
+```
+
+## Quickstart
+
+Create an API key in your Nestuge dashboard under **Settings → Developer**, then:
+
+```ts
+import Nestuge from '@nestuge/sdk';
+
+const nestuge = new Nestuge({ apiKey: process.env.NESTUGE_API_KEY! });
+
+// Verify your key works
+const { brandID, mode, scopes } = await nestuge.ping();
+
+// List your customers
+const { items } = await nestuge.customers.list({ limit: 50 });
+```
+
+Keys look like `nk_live_…` (production) or `nk_test_…` (test mode — requests validate and return previews without persisting live data).
+
+## Configuration
+
+```ts
+const nestuge = new Nestuge({
+  apiKey: 'nk_live_…',              // required
+  baseUrl: 'https://nestuge.com',   // default; use https://stg.nestuge.com for staging
+  maxRetries: 2,                    // extra attempts on 429/5xx/network errors
+  timeoutMs: 30_000,                // per-attempt timeout
+  fetch: customFetch,               // optional fetch override (proxies, testing)
+});
+```
+
+## Resources
+
+| Resource | Methods | Required scope |
+|---|---|---|
+| `nestuge.ping()` | — | none |
+| `nestuge.customers` | `list`, `retrieve`, `iterate` | `customers:read` |
+| `nestuge.products` | `list`, `retrieve`, `create`, `iterate` | `products:read` / `products:write` |
+| `nestuge.purchases` | `list`, `retrieve`, `iterate` | `purchases:read` |
+| `nestuge.transactions` | `list`, `retrieve`, `iterate` | `transactions:read` |
+| `nestuge.events` | `list`, `retrieve`, `create`, `iterate` | `events:read` / `events:write` |
+| `nestuge.tickets` | `retrieve`, `checkIn` | `purchases:read` / `purchases:write` |
+| `nestuge.webhooks` | `create`, `list`, `retrieve`, `update`, `del`, `test`, `iterate`, `verifySignature`, `constructEvent` | `webhooks:write` |
+| `nestuge.webhooks.deliveries` | `list`, `retrieve`, `resend`, `iterate` | `webhooks:write` |
+
+### Pagination
+
+`list()` returns one page: `{ items, hasMore, nextCursor }`. Pass `nextCursor` back as `cursor` for the next page — or let `iterate()` do it for you:
+
+```ts
+// Manual paging
+let page = await nestuge.purchases.list({ limit: 100 });
+while (page.hasMore) {
+  page = await nestuge.purchases.list({ limit: 100, cursor: page.nextCursor! });
+}
+
+// Auto paging
+for await (const purchase of nestuge.purchases.iterate()) {
+  console.log(purchase.id, purchase.title);
+}
+```
+
+### Creating a product
+
+```ts
+const product = await nestuge.products.create({
+  type: 'event',
+  title: 'Live Masterclass',
+  description: 'A 2-hour deep dive.',
+  imageUrl: 'https://example.com/cover.png',
+  price: { amount: 5000, currency: 'NGN' },
+  event: {
+    eventType: 'Zoom',
+    dateTime: '2026-08-01T18:00:00.000Z',
+  },
+});
+console.log(product.url); // shareable sales page
+```
+
+### Retrieving a product
+
+`retrieve()` returns a `ProductDetail` — the product plus its pricing `tiers` (payment plans) and `items` (content). `list()` returns the lighter `Product` shape without them.
+
+```ts
+const product = await nestuge.products.retrieve('reg_…');
+
+for (const tier of product.tiers) {
+  console.log(tier.name, tier.price.amount, tier.price.currency, tier.perks);
+}
+for (const item of product.items) {
+  console.log(item.title, item.type); // descriptive only — deliverables are never exposed
+}
+```
+
+### Checking in an event ticket
+
+```ts
+const ticket = await nestuge.tickets.checkIn('tkt_…');
+console.log(ticket.isCheckedIn, ticket.checkinTime);
+```
+
+## Webhooks
+
+Register an endpoint and store the signing secret — it is returned **once** and can never be retrieved again:
+
+```ts
+const endpoint = await nestuge.webhooks.create({
+  url: 'https://example.com/webhooks/nestuge',
+  events: ['transaction.succeeded', 'member.joined'],
+});
+await saveSecret(endpoint.signingSecret);
+```
+
+Verify and handle incoming events (Express example — note the **raw** body):
+
+```ts
+import express from 'express';
+import { constructEvent, WebhookVerificationError } from '@nestuge/sdk';
+
+const app = express();
+
+app.post('/webhooks/nestuge', express.raw({ type: 'application/json' }), async (req, res) => {
+  try {
+    const event = await constructEvent({
+      payload: req.body.toString('utf8'),
+      signature: req.header('X-Nestuge-Signature') ?? '',
+      secret: process.env.NESTUGE_WEBHOOK_SECRET!,
+    });
+
+    switch (event.type) {
+      case 'transaction.succeeded':
+        console.log(`Payment of ${event.data.amount} ${event.data.currency}`); // data: Transaction
+        break;
+      case 'member.joined':
+        console.log(`${event.data.name} joined hub ${event.data.hubID}`); // data: Customer
+        break;
+    }
+    res.sendStatus(200);
+  } catch (err) {
+    if (err instanceof WebhookVerificationError) return res.sendStatus(400);
+    throw err;
+  }
+});
+```
+
+`event` is a discriminated union — narrowing on `event.type` types `event.data` as a `Transaction` (`transaction.*`, `payout.settled`), `Purchase` (`subscription.*`), or `Customer` (`member.*`).
+
+Send yourself a sample event any time:
+
+```ts
+await nestuge.webhooks.test({ eventType: 'transaction.succeeded' });
+```
+
+## Error handling
+
+Every failed request throws a typed subclass of `NestugeError`:
+
+```ts
+import { NotFoundError, PermissionError, RateLimitError } from '@nestuge/sdk';
+
+try {
+  await nestuge.products.retrieve('reg_missing');
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    // 404 — doesn't exist or belongs to another brand
+  } else if (err instanceof PermissionError) {
+    // 403 — key is missing a scope, e.g. "products:read"
+  } else if (err instanceof RateLimitError) {
+    // 429 — err.retryAfter = seconds until the window resets
+  }
+}
+```
+
+| Error | When |
+|---|---|
+| `ValidationError` | 400 — bad body or params |
+| `AuthenticationError` | 401 — missing/invalid/revoked key |
+| `PermissionError` | 403 — key lacks a required scope |
+| `NotFoundError` | 404 — not found (or another brand's resource) |
+| `RateLimitError` | 429 — over 120 req/min (`retryAfter` in seconds) |
+| `ServerError` | 5xx |
+| `ConnectionError` | network failure or timeout |
+| `WebhookVerificationError` | webhook signature check failed |
+
+Retries on 429/5xx/network errors are automatic (default 2, exponential backoff, honors `Retry-After`).
+
+## License
+
+MIT