@convilyn/sdk 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable changes to `@convilyn/sdk` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/); this package adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-07-09
+
+### Added
+
+- **`goals.start({ llmConfigId })` / `goals.run({ llmConfigId })`** — optionally
+  pin a goal run to one of your stored BYO-LLM provider configs (created in the
+  console) so it runs on your own provider/key. Omit it to use your account
+  default. Serialised as `llmConfigId`; honoured only when BYO-LLM is enabled for
+  your account, otherwise the run uses the platform provider (parity with the
+  Python `convilyn` SDK).
+
+### Changed
+
+- **Default base URL corrected to `https://api.convilyn.corenovus.com`**
+  (was the non-serving `api.convilyn.com`), matching the Python consumer SDK.
+  Zero-config clients now reach the live API.
+- **`goals.events()` failure now points at `wait()` polling.** The platform
+  does not accept `ck_` keys on the WebSocket event stream in v1, so a connect
+  failure's `WebSocketError` message and the method docstring now spell out
+  that WebSocket streaming is polling-only for now (use `wait()`), mirroring
+  the Go consumer SDK's guidance.
+
+### Fixed
+
+- **README licence corrected to Apache-2.0** (it claimed MIT; the shipped
+  `LICENSE` file, `package.json`, and the Python SDKs are all Apache-2.0).
+  `publishConfig.access: public` is now pinned in `package.json` so a manual
+  publish of this scoped package cannot accidentally target restricted access.
+- **`convilyn doctor` no longer fails on runtimes without a global
+  `WebSocket`** (Node 18/20 — it is global only from Node 22). The capability
+  is optional: only `goals.events()` streaming needs it, and `goals.wait()`
+  polling covers the same ground, so the check now reports an advisory WARN
+  instead of failing the whole diagnostic with exit 1.
+- **`goals.start` reshapes seeded `slots` to `slotAnswers` on the create wire.**
+  The create endpoint (`CreateGoalJobRequest`) keys pre-seeded answers as
+  `slotAnswers: [{slotId, value}]`; the SDK sent the raw `{slotId: value}` dict
+  under `slots`, which the backend silently dropped — a seeded slot answer never
+  reached the job. `start({ slots })` now maps to the `slotAnswers` list (public
+  `slots` param unchanged). Mirrors the same fix in the Python SDK (`slots` →
+  `slotAnswers`).
+- **`convert.create` sends the snake_case `processor_type` discriminator.**
+  The conversion `JobRequest` discriminated union keys on `processor_type` per
+  the contract (`processorType` is only the *response* field name); the prior
+  camelCase request key was rejected by the backend with HTTP 400
+  `union_tag_not_found`, breaking every conversion. Conversions now succeed
+  against the current backend. Mirrors the same fix in the Python SDK.
+
+### Removed
+
+- **BREAKING: `GoalJob.workflowId`** — the backend's `GoalJobResponse` never
+  echoes `workflowId` (the *request* accepts it; the response does not), so the
+  property was always `null` at runtime. Removed pre-first-publish, so no
+  released consumer is affected. `goals.start({ workflowId })` /
+  `run({ workflowId })` and the `Workflow` / `WorkflowSummary` types are
+  unchanged. `GoalJob` is now conformance-mapped, so any future field the wire
+  doesn't speak fails CI instead of shipping silently.
+
+### Security
+
+- **https-only external presign URLs.** `externalGet` / `externalPut` now
+  refuse any backend-supplied URL whose scheme is not `https` (downgrade /
+  `file://` / unparseable → throw before any fetch), mirroring the Python
+  `_require_https` guard (internal `requireHttps`; not part of the public
+  barrel).
+- **Symlink refusal on `convert.downloadTo`.** Writing *through* a
+  pre-existing symlink target now throws; overwriting a regular file is
+  unchanged (parity with the Python `download_to` guard).
+
+## [0.1.0] — 2026-06-27
+
+### Added
+
+- Initial scaffold of the TypeScript consumer SDK (port of the Python
+  `convilyn` SDK).
+- Core transport seams: `AuthStrategy` + `ApiKey` + `resolveAuth`
+  (`CONVILYN_API_KEY`), `RetryPolicy` + `ExponentialBackoffRetry` + `NoRetry`,
+  and the `HttpClient` (fetch-based, retry loop + auto `Idempotency-Key` on
+  mutating verbs + typed error decoding + presigned-URL helpers).
+- The full typed-error hierarchy (`ConvilynError` → `AuthError` / `APIError` →
+  `RateLimitError` / `PlanRequiredError` / `QuotaExceededError` / `S3UploadError`
+  / `RetryExhaustedError`; `JobFailedError` / `JobTimeoutError` /
+  `GoalJobFailedError` / `GoalJobTimeoutError` / `WebSocketError`).
+- The wire/domain type interfaces (`File`, `ConvertJob`, `GoalJob`, `GoalEvent`,
+  `Workflow*`, `CostEstimate`, …).
+- The `files` resource (`upload`: presign → upload PUT → confirm; path or raw
+  bytes, MIME auto-detection) and the `convert` resource (`create` / `retrieve` /
+  `wait` / `createAndWait` / `downloadUrl` / `downloadTo`, with poll-backoff and
+  `JobFailedError` / `JobTimeoutError`).
+- The `Convilyn` client exposing all five resources: `files`, `convert`,
+  `goals`, `workflows`, `account`.
+- The `goals` resource (agentic workflow runs): `start` / `retrieve` / `wait`
+  (terminal + HITL stop) / `run` / `fillSlot` / `fillSlots` / `confirm` /
+  `cancel` / `retry`, plus `events()` — an `AsyncIterableIterator<GoalEvent>`
+  over a WebSocket, with the `WSTransport` DIP seam, `GoalJobFailedError` /
+  `GoalJobTimeoutError`, and strict envelope validation.
+- The `workflows` resource (`search` / `get` / `fork` / `publish` / `patch` /
+  `like`) and the `account` resource (`getQuota` / `getPlan` / `usageHistory`).
+  Cost-preview amounts are exposed in **credits** (the µU wire is converted at
+  10,000 µU = 1 credit).
+- The `convilyn` CLI (commander) — `convert`, `goals` (start/status/events/
+  fill-slot/confirm/cancel/retry), `account` (plan/quota), `api` (gh-style
+  escape hatch), and `doctor`. `--json` for machine output, `--dry-run` where
+  applicable, and pinned exit codes (0 ok / 1 usage / 2 api / 3 job-failed /
+  130 sigint) via the `OutputRenderer` seam.
+- Release tooling: the npm publish workflow (provenance via OIDC, tag-gated),
+  the shared SDK black-box blacklist lint extended over the TS surface, npm
+  Dependabot tracking, and packaging guards (version↔CHANGELOG lockstep +
+  public-surface importability).
+- Opt-in auto-throttle: `AutoThrottleConfig` + the `autoThrottle` client option
+  sleep + re-issue on a 402 `QUOTA_EXCEEDED` envelope (waiting for the quota
+  window, distinct from the transient-failure retry policy), and a
+  `X-Quota-State: soft_limit` signal is surfaced via `process.emitWarning`
+  (parity with the Python SDK's throttle module).
+- Consumer/Author key boundary: only the `ck_` consumer key is accepted. An
+  Author-SDK / deploy token now raises a guiding `AuthError` instead of
+  producing an opaque 401; unknown prefixes are still accepted for
+  forward-compat.
+
+### Changed
+
+- The public resilience + transport contracts (`RetryPolicy` /
+  `ExponentialBackoffRetry` / `NoRetry`, and the `WSTransport` seam) now live in
+  public modules (`src/retry.ts`, `src/transport.ts`) — no published contract is
+  re-exported from `internal/`. A strengthened packaging guard pins the exact
+  public runtime surface, scans for internal/Author-token leaks, and asserts the
+  `package.json` `exports` map exposes only the root entry.
+- Rewrote the README into a complete guide (auth, all five resources, error
+  handling, retry/timeout/auto-throttle, WebSocket events, CLI) with a "Public
+  API & Stability" section codifying the SemVer surface.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept (and charge a
+      fee for) acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 CoreNovus contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,282 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/CoreNovus/convilyn-js/main/docs/assets/corenovus-community-banner.png" alt="CoreNovus Community — Connected AI Workflows" />
+</p>
+
+# @convilyn/sdk
+
+[![CI](https://github.com/CoreNovus/convilyn-js/actions/workflows/ci.yml/badge.svg)](https://github.com/CoreNovus/convilyn-js/actions/workflows/ci.yml)
+
+Official Convilyn client SDK for TypeScript / JavaScript — file conversion,
+agentic goal workflows, and a community library for reusable AI workflows. A
+faithful port of the Python `convilyn` SDK: same wire contract, idiomatic async
+TypeScript surface. Ships ESM + CJS + type declarations, with a `convilyn` CLI.
+
+Convilyn helps people turn repeated AI-assisted work into workflows that can be
+run again, shared, and improved. It is part of the CoreNovus vision for
+practical AI workflows across cloud services, local machines, AI PCs, edge
+devices, and future IoT environments.
+
+> **Public mirror** of Convilyn's monorepo (the source of truth). Contributions
+> are welcome and land in the shipped package — see
+> **[CONTRIBUTING.md](CONTRIBUTING.md)** (fork → PR → upstreamed, authorship
+> preserved).
+
+## What is Convilyn?
+
+Convilyn is an open source SDK for building with free file conversion tools and
+practical AI workflow capabilities. Its main value is helping people use the
+computing resources they already have — local machines, AI PCs, and edge
+devices — to run practical AI workflows without depending entirely on paid
+cloud services.
+
+## Who is this for?
+
+- Developers building reusable AI workflow components
+- People working with file conversion and automation
+- Builders experimenting with local-first AI workflows
+- Communities that want open, practical AI tooling
+- Contributors who want to help make AI workflows easier to use and share
+
+## Install
+
+```bash
+npm install @convilyn/sdk      # or: pnpm add @convilyn/sdk / yarn add @convilyn/sdk
+```
+
+Requires **Node 18+** (uses the global `fetch`) or any modern browser bundler. The
+only runtime dependency is `commander` (for the CLI).
+
+## Authentication
+
+The SDK authenticates with a **consumer API key** — it starts with `ck_`. Mint one
+in the Convilyn web app under **Settings → API**.
+
+```ts
+import { Convilyn } from '@convilyn/sdk'
+
+// Explicit:
+const client = new Convilyn({ apiKey: 'ck_…' }) // pragma: allowlist secret
+
+// Or omit it and the SDK reads the CONVILYN_API_KEY environment variable:
+const client = new Convilyn()
+```
+
+> `ck_` is the **only** consumer key. `cvl_` / `cvi_` are *Author SDK* / deploy
+> tokens (for publishing workflows and tools) — passing one here throws an
+> `AuthError` pointing you to the right key.
+
+## Quickstart
+
+Convert a local document to PDF:
+
+```ts
+import { Convilyn } from '@convilyn/sdk'
+
+const client = new Convilyn({ apiKey: process.env.CONVILYN_API_KEY })
+
+const file = await client.files.upload({ path: 'report.docx' })
+const job = await client.convert.createAndWait({ file, targetFormat: 'pdf' })
+await client.convert.downloadTo(job, { to: 'report.pdf' })
+
+await client.close()
+```
+
+Run an agentic goal workflow and wait for the result:
+
+```ts
+const result = await client.goals.run({
+  workflowId: 'wf_grade_sheet',
+  files: [file.fileId],
+})
+console.log(result.status) // 'completed' | 'partial' | 'failed' | 'slots_pending' | …
+```
+
+## Resources
+
+The client exposes five resources: `files`, `convert`, `goals`, `workflows`,
+`account`.
+
+### `files` — upload
+
+```ts
+const fromPath = await client.files.upload({ path: 'a.pdf' })             // Node
+const fromBytes = await client.files.upload({ content: bytes, filename: 'a.pdf' }) // browser-safe
+```
+
+### `convert` — document conversion
+
+```ts
+const job = await client.convert.create({ file, targetFormat: 'pdf' })
+const done = await client.convert.wait(job.jobId)            // poll to terminal
+const url = await client.convert.downloadUrl(done)           // presigned URL
+await client.convert.downloadTo(done, { to: 'out.pdf' })     // Node: stream to disk
+```
+
+`createAndWait` is the `create` + `wait` shortcut. A `failed` job throws
+`JobFailedError`; an elapsed deadline throws `JobTimeoutError`.
+
+### `goals` — agentic goal workflows
+
+```ts
+const job = await client.goals.start({ goalText: 'Summarise this', files: [file.fileId] })
+const state = await client.goals.wait(job.jobSpecId)         // stops at terminal OR a HITL slot
+
+if (state.status === 'slots_pending') {
+  await client.goals.fillSlot(state.jobSpecId, { slotId: state.pendingSlots[0]!.slotId, value: 'A1' })
+  await client.goals.confirm(state.jobSpecId)
+}
+```
+
+Other methods: `retrieve`, `run` (`start` + `wait`), `fillSlots`, `cancel`,
+`retry`, and `events()` (see [WebSocket events](#websocket-events) below).
+
+### `workflows` — community marketplace
+
+```ts
+const page = await client.workflows.search({ tag: 'finance', sort: 'popular' })
+const wf = await client.workflows.get(page.items[0]!.workflowId)
+const mine = await client.workflows.fork({ sourceSpecId: wf.specId, name: 'My copy' }) // Pro
+await client.workflows.publish(mine.workflowId, { itemVersion: mine.itemVersion })     // Pro
+await client.workflows.like(wf.workflowId)
+```
+
+### `account` — plan, cost preview & usage (read-only)
+
+```ts
+const plan = await client.account.getPlan()                 // { tier: 'free' | 'pro' }
+const estimate = await client.account.getQuota({ tools: ['pdf-mcp:extract_text'] })
+console.log(estimate.estimatedCredits, estimate.quotaCheck.state)
+const history = await client.account.usageHistory({ since: new Date('2026-06-01') })
+```
+
+Money is always expressed in **credits** (1 credit = $0.01) — never internal
+micro-units.
+
+## Error handling
+
+Every SDK failure is a subclass of `ConvilynError`; branch on `code` / `statusCode`
+for typed handling.
+
+```ts
+import { ConvilynError, QuotaExceededError, RateLimitError, PlanRequiredError } from '@convilyn/sdk'
+
+try {
+  await client.goals.run({ goalText: '…', files: [file.fileId] })
+} catch (err) {
+  if (err instanceof QuotaExceededError) {
+    console.error(`Need ${err.costCredits} credits, have ${err.balanceCredits}. Top up: ${err.topUpUrl}`)
+  } else if (err instanceof PlanRequiredError) {
+    console.error(`Upgrade required: ${err.upgradeUrl}`)
+  } else if (err instanceof RateLimitError) {
+    console.error('Rate limited — back off and retry.')
+  } else if (err instanceof ConvilynError) {
+    console.error('SDK error:', err.message)
+  } else {
+    throw err
+  }
+}
+```
+
+The hierarchy: `ConvilynError` → `AuthError`, `APIError` (→ `RateLimitError`,
+`PlanRequiredError`, `QuotaExceededError`, `S3UploadError`, `RetryExhaustedError`),
+`JobFailedError`, `JobTimeoutError`, `GoalJobFailedError`, `GoalJobTimeoutError`,
+`WebSocketError`.
+
+## Retry, timeout & auto-throttle
+
+```ts
+import { Convilyn, ExponentialBackoffRetry, NoRetry, AutoThrottleConfig } from '@convilyn/sdk'
+
+const client = new Convilyn({
+  timeout: 30,                                  // per-request, in seconds
+  maxRetries: 5,                                // cap (0 = no retries); or pass a full policy:
+  retryPolicy: new ExponentialBackoffRetry({ maxAttempts: 5, baseDelay: 0.2, maxDelay: 30 }),
+  autoThrottle: true,                           // sleep+retry on a 402 quota error
+})
+```
+
+- **`retryPolicy` / `maxRetries`** handle *transient* transport failures
+  (408 / 429 / 5xx) with capped exponential backoff + jitter, honouring
+  `Retry-After`. Pass `new NoRetry()` to fail fast.
+- **`autoThrottle`** is a distinct, opt-in shim for the **402 `QUOTA_EXCEEDED`**
+  envelope, where the remedy is *waiting for the quota window* rather than
+  retrying faster. `true` enables the defaults (1 retry, 60 s cap); pass
+  `new AutoThrottleConfig({ maxRetries: 2, maxSleep: 120, fallbackSleep: 5 })` to
+  tune. A soft-limit signal (`X-Quota-State: soft_limit`) is surfaced via Node's
+  `process.emitWarning` whether or not auto-throttle is enabled.
+
+## WebSocket events
+
+`goals.events()` streams live execution events as an async iterator:
+
+```ts
+for await (const event of client.goals.events(job.jobSpecId)) {
+  console.log(event.type, event.data)   // 'tool_started' | 'progress' | 'completed' | …
+}
+```
+
+> **Known v1 limitation:** the platform does not yet accept `ck_` keys for the
+> WebSocket event stream. Until that lands, prefer polling with `goals.wait()`
+> (which uses standard HTTP auth and works today); `events()` is wired and ready
+> for when consumer-key streaming ships. There is no auto-reconnect — the
+> backend does not replay missed events, so a silent reconnect would hide gaps.
+
+## CLI
+
+The package installs a `convilyn` binary:
+
+```bash
+export CONVILYN_API_KEY=ck_…
+convilyn doctor --ping                            # environment + backend connectivity
+convilyn convert a.docx --to pdf -o a.pdf
+convilyn goals start --goal-text "Summarise" --files f_123
+convilyn goals status <jobSpecId> --watch
+convilyn goals events <jobSpecId>
+convilyn account plan
+convilyn account quota --tool pdf-mcp:extract_text
+convilyn api GET /api/v1/health                   # gh-style escape hatch
+```
+
+`--json` emits machine-readable output. Exit codes are pinned: `0` ok, `1` usage,
+`2` API error, `3` job failed, `130` interrupted.
+
+## Configuration reference
+
+| Constructor option | Env var | Default |
+|---|---|---|
+| `apiKey` | `CONVILYN_API_KEY` | — (required) |
+| `baseUrl` | `CONVILYN_BASE_URL` (CLI only) | `https://api.convilyn.corenovus.com` |
+| `wsUrl` | `CONVILYN_WS_URL` | — |
+| `timeout` (seconds) | — | `30` |
+| `maxRetries` / `retryPolicy` | — | 5-attempt backoff |
+| `autoThrottle` | — | disabled |
+| `disableIdempotency` | — | `false` |
+
+## Public API & Stability
+
+This package follows [Semantic Versioning](https://semver.org/). **The SemVer
+contract is exactly the set of names exported from the package root** — the
+`Convilyn` client and its resources, the error classes, the wire/response types,
+the retry policies + `AutoThrottleConfig`, the `WSTransport` seam, and `VERSION`:
+
+```ts
+import { Convilyn, QuotaExceededError, ExponentialBackoffRetry, AutoThrottleConfig } from '@convilyn/sdk'
+```
+
+Anything **not** exported here — the HTTP transport, the auth strategy, parsers,
+the concrete WebSocket adapter — is internal and may change in any release. The
+`package.json` `exports` map blocks deep imports of those paths, and a packaging
+test pins the public surface so it cannot grow by accident. While the package is
+pre-1.0 (`0.x`), minor versions may still contain breaking changes; once it
+reaches `1.0.0`, breaking changes will only land in major versions.
+
+### Relationship to the Python SDK
+
+The public surface mirrors the Python SDK's `__all__`. Two intentional,
+idiomatic differences: there is a single promise-based `Convilyn` (JavaScript has
+no sync/async split, so there is no separate `AsyncConvilyn`), and the version
+constant is `VERSION` (vs Python's `__version__`).
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).