@exayard/sdk 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Exayard
+
+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,139 @@
+# @exayard/sdk
+
+Official TypeScript SDK for the [Exayard](https://exayard.com) API: AI takeoffs, estimates, bids, price lists and
+webhooks. Every API operation is a typed method, generated from the API spec.
+
+## Install
+
+```bash
+npm install @exayard/sdk
+```
+
+Node 20 or later (or any runtime with `fetch` and Web Crypto).
+
+## Quickstart
+
+Create an app and a key on the Developer page ([exayard.com/settings/developer](https://exayard.com/settings/developer)).
+A sandbox company gives you an `exa_test_` key whose AI work returns sample results at no cost.
+
+```ts
+import { readFile } from 'node:fs/promises'
+import { Exayard } from '@exayard/sdk'
+
+// A key made for a company acts in that company: no organizationId needed.
+const exa = new Exayard({ apiKey: process.env.EXAYARD_API_KEY })
+
+const project = await exa.projects.create({ name: 'Riverside clinic' })
+const { fileId } = await exa.files.upload({
+  projectId: project.id,
+  filename: 'plans.pdf',
+  mimeType: 'application/pdf',
+  bytes: await readFile('plans.pdf')
+})
+const pages = await exa.pages.list(project.id)
+```
+
+Every operation is also on `exa.api` (camelCase) and `exa.call` (by its operation name):
+
+```ts
+await exa.api.listVendorQuotes({ id: project.id })
+await exa.call('list_vendor_quotes', { id: project.id })
+```
+
+## Keys and companies
+
+- `exa_live_...` and `exa_test_...` keys work, and so do the older `ak_...` keys and `xa_app_...` app secrets.
+  `apiKey` defaults to the `EXAYARD_API_KEY` environment variable. An OAuth access token goes in `bearerToken`.
+- `organizationId` is optional everywhere. A key made for its own company implies that company. A personal key or
+  sign-in that belongs to several companies names one with the client's `organizationId` or on the call.
+
+## End users
+
+If you call Exayard for your own customers, name the customer so usage can be broken down by end user (on the
+Usage screen and through the usage API):
+
+```ts
+const exa = new Exayard({ apiKey, endUser: 'customer-1842' })
+await exa.projects.list({}) // sent with Exayard-End-User: customer-1842
+await exa.call('get_project', { id }, { endUser: 'customer-77' }) // per call
+```
+
+An end user id is 1 to 128 printable characters. Use your own opaque id, never an email address.
+
+## Retries and idempotency
+
+429s, 5xx answers and dropped connections are retried twice by default, waiting as long as `Retry-After` asks (up to
+a minute) or backing off from half a second. Every POST, PATCH, PUT and DELETE carries an `Idempotency-Key` that each
+retry reuses, so a retried call runs once. Pass your own with `{ idempotencyKey }`, and set `maxRetries` on the client
+or the call (`0` turns retries off).
+
+## Errors
+
+Every failed call throws an `ExayardError` subclass chosen by the problem's `code`:
+
+| Class | Status | Codes |
+|---|---|---|
+| `BadRequestError` | 400 | `invalid_request`, `invalid_end_user`, `company_required`, `company_mismatch` |
+| `AuthenticationError` | 401 | `unauthenticated`, `api_key_expired` |
+| `PaymentRequiredError` | 402 | `insufficient_credits`, `usage_limit_reached`, `subscription_required`, ... |
+| `PermissionDeniedError` | 403 | `forbidden`, `insufficient_scope`, `app_not_installed`, `app_suspended` |
+| `NotFoundError` | 404 | `not_found` |
+| `ConflictError` | 409 | `conflict`, `idempotency_key_reused` |
+| `RateLimitError` | 429 | `rate_limited` (with `retryAfter`) |
+| `InternalServerError` | 5xx | `internal_error` |
+| `APIConnectionError` | none | `connection_error`, `timeout` |
+
+```ts
+try {
+  await exa.projects.get(id)
+} catch (err) {
+  if (err instanceof NotFoundError) return null
+  throw err // err.code, err.detail, err.requestId, err.docUrl
+}
+```
+
+## Webhooks
+
+Verify a delivery with the raw request body, the `Exayard-Signature` header and the endpoint's `whsec_` secret.
+`constructWebhookEvent` is async (it uses Web Crypto), so `await` it. It needs no API key; `exa.webhooks.constructEvent`
+is the same function. With Express:
+
+```ts
+import express from 'express'
+import { constructWebhookEvent, WebhookSignatureError } from '@exayard/sdk'
+
+const secret = process.env.EXAYARD_WEBHOOK_SECRET
+if (!secret) throw new Error('Set EXAYARD_WEBHOOK_SECRET')
+
+const app = express()
+
+// Take the raw body (a Buffer), not express.json(): the signature covers the exact bytes sent.
+app.post('/webhooks', express.raw({ type: 'application/json' }), async (req, res) => {
+  try {
+    const event = await constructWebhookEvent(req.body, req.get('Exayard-Signature'), secret)
+    if (event.type === 'assessment.completed') {
+      // ...
+    }
+    res.sendStatus(200)
+  } catch (err) {
+    if (err instanceof WebhookSignatureError) res.status(400).send(err.code)
+    else res.sendStatus(500)
+  }
+})
+
+app.listen(3000)
+```
+
+It throws `WebhookSignatureError` (`invalid_signature`, `replay_window_exceeded`, `malformed_header`); answer it with
+a 400. To receive events on your own machine without a public address, run `exayard listen --forward-to
+http://localhost:3000/webhooks` from [`@exayard/cli`](https://www.npmjs.com/package/@exayard/cli), or use
+`exa.webhooks.listeners` directly.
+
+## Links
+
+- API reference: https://developers.exayard.com/api-reference
+- Errors: https://developers.exayard.com/concepts/errors
+
+## License
+
+MIT