@spreadspace/embed 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpreadSpace
+
+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,128 @@
+# @spreadspace/embed
+
+Server-side Node.js SDK for [SpreadSpace](https://spreadspace.app) embeds —
+mints the short-lived embed sessions that authorize the browser widget, and
+verifies SpreadSpace webhooks. For general API access from TypeScript, use
+[`@spreadspace/sdk`](https://www.npmjs.com/package/@spreadspace/sdk).
+
+```bash
+npm install @spreadspace/embed
+# or
+pnpm add @spreadspace/embed
+```
+
+Server-side use only. Don't ship this package to a browser — API keys must
+never appear in client code. For browser embedding, use the
+`<SpreadSpaceReview />` widget with a short-lived embed token minted via this
+SDK.
+
+## Quickstart
+
+### 1. Mint an embed token
+
+```ts
+import { SpreadSpaceClient } from '@spreadspace/embed';
+
+const client = new SpreadSpaceClient({
+  apiKey: process.env.SPREADSPACE_API_KEY!, // 'ss_live_...' or 'ss_test_...'
+});
+
+const session = await client.embed.sessions.create({
+  loan_id: 'loan_abc',
+});
+
+// Pass session.embed_token to the browser. It is scoped to this single loan
+// and expires automatically.
+```
+
+### 2. Verify a webhook
+
+```ts
+import { verifyAndParseWebhook } from '@spreadspace/embed/webhooks';
+
+app.post('/webhooks/spreadspace', async (req, res) => {
+  const event = verifyAndParseWebhook(
+    req.rawBody, // the exact bytes received — not re-stringified JSON
+    req.headers['spreadspace-signature'] as string,
+    process.env.SPREADSPACE_WEBHOOK_SECRET!,
+  );
+
+  switch (event.type) {
+    case 'extraction.ready':
+      // event.data is typed as ExtractionReadyPayload
+      await markExtractionReady(event.data.loan_id, event.data.extraction_id);
+      break;
+    case 'job.completed':
+      // event.data is typed as JobCompletedPayload
+      break;
+  }
+  res.status(200).end();
+});
+```
+
+### 3. Iterate over loans
+
+```ts
+for await (const loan of client.loans.list({ borrower_id: 'br_xyz' })) {
+  console.log(loan.id, loan.borrower_id);
+}
+```
+
+The list iterator handles cursor pagination automatically — no manual
+`next_cursor` plumbing.
+
+## What you get
+
+- **Typed client** for every endpoint, organized into Stripe-style
+  resources (`client.loans`, `client.borrowers`, `client.documents`, etc.).
+- **Automatic retries** on `429` and `5xx` responses with exponential
+  backoff and full jitter; honors `Retry-After`.
+- **Auto-generated `Idempotency-Key`** on every non-GET request so retries
+  are safe by default. Override or suppress per-request.
+- **Auto-pinned `SpreadSpace-Version`** header — the SDK ships with the API
+  surface it was built against.
+- **Webhook signature verifier** — byte-for-byte compatible with the
+  server-side signer, available as a tree-shakeable
+  `@spreadspace/embed/webhooks` import for receiver Lambdas.
+- **Async iterators** for paginated list endpoints (`for await`,
+  `.toArray()`, or `.pages()` for batch processing).
+- **Typed errors** —
+  `SpreadSpaceError` / `RateLimitError` / `PermissionError` / etc. — for
+  `instanceof`-based handling.
+
+## Configuration
+
+```ts
+new SpreadSpaceClient({
+  apiKey: 'ss_live_...',
+  baseUrl: 'https://api.spreadspace.app', // override for staging / local
+  apiVersion: '2026-05-03',              // override the SDK-pinned version
+  timeout: 30_000,                       // ms per HTTP attempt
+  maxRetries: 3,                         // retry budget for 429 / 5xx
+});
+```
+
+## Errors
+
+```ts
+import { SpreadSpaceClient, RateLimitError, PermissionError } from '@spreadspace/embed';
+
+try {
+  await client.borrowers.retrieve('br_xyz');
+} catch (err) {
+  if (err instanceof PermissionError && err.type === 'pii_claim_required') {
+    // err.details.borrower_id, err.details.claim_endpoint are set
+  } else if (err instanceof RateLimitError) {
+    // SDK already retried `maxRetries` times — the integrator may want to
+    // back off harder or surface to the caller.
+  }
+}
+```
+
+Every thrown `SpreadSpaceError` carries `requestId` (the server-generated
+`X-Request-ID`), `type` (the canonical error-type string from the API
+envelope), and `statusCode`. Quote `requestId` in support tickets.
+
+## License
+
+MIT.