@pantechdynamic/sdk 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+A new version heading here (`## X.Y.Z (YYYY-MM-DD)`) pushed to main is
+tagged `vX.Y.Z` and published to npm. Add changes under `## Unreleased`
+until then.
+
+## 0.2.0 (2026-10-28)
+
+- `client.migrate`, for moving from another cloud: `migrate.connections`
+  (`list`, `listAll`, `create`, `get`, `update` for the name, role ARN or a retry, `delete`)
+  connects an AWS account through a read-only role; `migrate.scans` (`list`, `listAll`,
+  `start`, `get` with `{ include: "inventory" }`) reads what runs there; `migrate.migrations`
+  (`list`, `listAll`, `create`, `get`, `rename`, `delete`, `updateItem`, `exportTerraform`) plans
+  the move with a price comparison and a Terraform export.
+- `migrate.connections.wait()` and `migrate.scans.wait()`, which reject with the new
+  `CloudFailedError` when the connection or scan fails.
+- `examples/migrate-from-aws.ts`.
+- Types follow the current public API, including Kubernetes clusters' `node_health`,
+  `ready_nodes` and `nodes_checked_at`, and a load balancer's `protocol`.
+- Fixed: request fields the API defaults (`endpoint_access`, `control_nodes`, a firewall rule's
+  `direction` and `action`, `algorithm`, `purpose`, `admin_username`, `retention_count`,
+  `enabled`, `autoscaling_enabled`) are optional in the types, as they are in the API.
+- Agent sessions, which answer only AI apps connected through Pantech's MCP server, have no
+  methods yet; `scripts/not-in-sdk.json` lists them and `npm run generate` leaves out their types.
+
+## 0.1.0 (2026-10-24)
+
+- First release: a client for every operation in the Pantech Dynamics public API
+  (`/public/v1`), with types generated from its OpenAPI spec.
+- Automatic `Idempotency-Key` on every write, reused across retries; retries with
+  backoff and `Retry-After` on network errors, 429, 500, 502, 503 and 504, except for
+  writes the API does not replay.
+- `PantechError` and its subclasses, carrying `status`, `code`, `title`, `detail`,
+  `requestId` and field `errors`.
+- `listAll()` async iterators, `operations.wait()`, `operations.stream()`, and
+  `instanceOrders.wait()` / `databaseOrders.wait()`.
+- `me.revoke()` (`DELETE /me`), and `kind` / `client_name` on `me.get()`.
+- `verifyWebhook()` and `signWebhook()` on Web Crypto.
+- ESM and CommonJS builds; Node.js 18+, Bun, Deno and edge runtimes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pantech Dynamics
+
+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

@@ -1,3 +1,201 @@
-# Temporary Holding Version
+# Pantech Dynamics SDK for TypeScript and JavaScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/Pantech-Dynamics/pantech-js/actions/workflows/ci.yml/badge.svg)](https://github.com/Pantech-Dynamics/pantech-js/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@pantechdynamic/sdk.svg)](https://www.npmjs.com/package/@pantechdynamic/sdk)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+The official client for the [Pantech Dynamics public API](https://docs.pantechdynamics.com/api):
+instances, VPC networks, firewalls, public IPs, load balancers, volumes, snapshots, managed
+databases, managed Kubernetes, SSH keys, webhooks, billing, usage, and moving from another cloud.
+
+- Zero runtime dependencies. Uses the global `fetch` and Web Crypto, so it runs on Node.js 18+,
+  Bun, Deno and edge runtimes.
+- ESM and CommonJS, with types generated from the API's OpenAPI spec.
+- Retries, idempotency keys, typed errors, pagination, operation waiting and webhook
+  verification built in.
+
+```sh
+npm install @pantechdynamic/sdk
+```
+
+## Quickstart
+
+Create an API key in the console under **Organization › API keys**, then:
+
+```ts
+import { Pantech } from "@pantechdynamic/sdk";
+
+const client = new Pantech({ apiKey: process.env.PANTECH_API_KEY });
+
+// Order an instance and wait until it is running.
+const order = await client.instances.create({
+  name: "web-1",
+  plan_slug: "starter",
+  image_slug: "ubuntu-24-04",
+  ssh_key_id: "sshk_…",
+});
+await client.instanceOrders.wait(order);
+
+const vm = await client.instances.get(order.instance_id);
+console.log(vm.public_ipv4);
+
+// Every write returns an operation; wait for it.
+await client.operations.wait(await client.instances.stop(vm.id));
+```
+
+`apiKey` defaults to `PANTECH_API_KEY`, and `baseURL` to `PANTECH_API_URL`, else
+`https://api.pantechdynamics.com/public/v1`. Request and response fields are exactly as the API
+sends them (`plan_slug`, `next_cursor`); methods are camelCase.
+
+```ts
+new Pantech({
+  apiKey: "PAN_…",
+  baseURL: "https://api.example.com/public/v1",
+  maxRetries: 3, // default
+  timeout: 60_000, // per attempt, in ms (default)
+  fetch: customFetch, // default: globalThis.fetch
+});
+```
+
+Every method takes per-call options last: `{ signal, timeout, maxRetries, idempotencyKey, headers }`.
+
+## Resources
+
+| Family | Examples |
+|---|---|
+| Account | `me.get()`, `me.revoke()` |
+| Catalogue | `regions.list()`, `plans.list({ placement })`, `images.list()`, `diskOfferings.quote(slug, { size_gb })`, `databaseEngines.list()`, `kubernetesVersions.list()`, `pricing.estimate({...})` |
+| Instances | `instances.list/listAll/create/get/delete/start/stop/reboot/rebuild/rename/resize/restore/…`, `instances.snapshots.*`, `instances.sshAccess.*`, `instanceOrders.wait(order)` |
+| Networks | `networks.*`, `networks.subnets.list(networkId)`, `networks.firewallRules.create(subnetId, {...})` |
+| Public IPs | `publicIps.*`, `publicIps.portForwardingRules.*` |
+| Load balancers | `loadBalancers.*` |
+| Kubernetes | `kubernetes.*`, `kubernetes.nodePools.*`, `kubernetes.addons.toggle(...)` |
+| Security groups | `securityGroups.*`, `securityGroups.replaceRules(id, {...})` |
+| Volumes and snapshots | `volumes.*`, `volumes.snapshots.*`, `snapshots.*` |
+| Databases | `databases.*`, `databases.snapshots.*`, `databaseOrders.wait(order)` |
+| SSH keys, webhooks | `sshKeys.*`, `webhooks.*`, `webhooks.deliveries.*` |
+| Billing and usage | `billing.credit.get()`, `billing.credit.purchases.create(...)`, `billing.receipts.getPdf(id)`, `usage.get()` |
+| Move from another cloud | `migrate.connections.*`, `migrate.scans.*`, `migrate.migrations.*` |
+| Operations | `operations.get(id)`, `operations.wait(id)`, `operations.stream(id)` |
+
+Every operation in the public spec has a method, except agent sessions, which answer only AI apps
+connected through Pantech's MCP server; `test/coverage.test.ts` fails if one is missing.
+For anything else, `client.request({ method, path, query, body })` sends a raw request with the
+same auth, retries and errors.
+
+## Pagination
+
+`list()` returns one page (`{ data, next_cursor }`). `listAll()` follows the cursor for you:
+
+```ts
+for await (const vm of client.instances.listAll({ observed_state: "running" })) {
+  console.log(vm.id, vm.name);
+}
+for await (const subnet of client.networks.subnets.listAll("net_…")) console.log(subnet.cidr);
+```
+
+## Waiting
+
+```ts
+const op = await client.operations.wait(accepted, { timeoutMs: 10 * 60_000, onUpdate: (o) => console.log(o.status) });
+await client.databaseOrders.wait(order); // paid, provisioned, and its create operation done
+for await (const o of client.operations.stream("op_…")) console.log(o.status); // Server-Sent Events
+```
+
+A failed operation rejects with `OperationFailedError` (`code`, `detail` from its `failure`), a
+failed or unpaid order with `OrderFailedError`, a failed cloud connection or scan with
+`CloudFailedError`, and a wait that runs out with `WaitTimeoutError`.
+
+## Move from another cloud
+
+`client.migrate` connects an AWS account through a read-only role that only Pantech can assume (no
+access keys are shared), scans what runs there, and plans the move with a price comparison and a
+Terraform export. Nothing is created on Pantech until you apply the Terraform.
+
+```ts
+let conn = await client.migrate.connections.create({ name: "Production AWS" });
+console.log(conn.setup.quick_create_url); // create the stack in AWS, then send its RoleArn output
+await client.migrate.connections.update(conn.id, { role_arn: "arn:aws:iam::…:role/…" });
+conn = await client.migrate.connections.wait(conn.id); // CloudFailedError if the role cannot be assumed
+
+const scan = await client.migrate.scans.wait((await client.migrate.scans.start(conn.id)).id);
+const plan = await client.migrate.migrations.create({ scan_id: scan.id, name: "Move to Pantech" });
+console.log(plan.estimate?.pantech_monthly_minor, plan.estimate?.source_monthly_minor);
+const { files } = await client.migrate.migrations.exportTerraform(plan.id); // main.tf, variables.tf
+```
+
+`migrate.migrations.updateItem(id, { key, excluded: true })` leaves an item out, or changes its
+plan, size, address range or role, before you export. See `examples/migrate-from-aws.ts`.
+
+## Errors
+
+Every error is a `PantechError` carrying `status`, `code`, `title`, `detail`, `requestId` and
+`errors` (the field errors of a `422`). Branch on `code`, never on the message:
+
+```ts
+import { isPantechError, NotFoundError } from "@pantechdynamic/sdk";
+
+try {
+  await client.instances.get("vm_…");
+} catch (err) {
+  if (err instanceof NotFoundError) { /* gone */ }
+  else if (isPantechError(err, "INSUFFICIENT_SCOPE")) { /* key lacks a scope */ }
+  else throw err;
+}
+```
+
+Subclasses: `BadRequestError` (400), `AuthenticationError` (401), `PaymentRequiredError` (402),
+`PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `ValidationError`
+(422), `RateLimitError` (429), `InternalServerError` (5xx), `APIConnectionError` and
+`APITimeoutError` (no answer).
+
+## Retries and idempotency
+
+Every POST, PUT, PATCH and DELETE carries an `Idempotency-Key` (a random UUID, or yours via
+`idempotencyKey`), and every retry of that call reuses it, so a change cannot happen twice.
+Network errors, timeouts, `429` (after `Retry-After`), `500`, `502`, `503` and `504` are retried up
+to `maxRetries` times with jittered backoff.
+
+The API does not replay some writes by key, so the SDK sends them once (except after a `429`,
+which is refused before anything runs): creating and deleting SSH keys, opening an instance
+console, issuing a volume key credential, testing, deleting, rotating the secret of and
+redelivering webhooks, and `DELETE /me`.
+
+## Webhooks
+
+```ts
+import { verifyWebhook } from "@pantechdynamic/sdk";
+
+await verifyWebhook({
+  secret: process.env.PANTECH_WEBHOOK_SECRET!,
+  header: request.headers.get("Pantech-Signature"),
+  body: await request.text(), // the raw body, not re-serialised JSON
+  toleranceSeconds: 300, // default
+});
+```
+
+It rejects with `WebhookVerificationError` when the signature does not match any `v1` value or
+the timestamp is too old. On Node.js 18, start node with `--experimental-global-webcrypto`
+(Node.js 20+ needs nothing). See `examples/webhook-receiver.ts`.
+
+## Examples
+
+`examples/` has `create-instance.ts`, `list.ts`, `webhook-receiver.ts` and `migrate-from-aws.ts`. With Node.js 23.6+:
+`npm run build && PANTECH_API_KEY=PAN_… node examples/list.ts`.
+
+## Development
+
+```sh
+npm ci
+npm run spec:sync   # download the published spec into spec/public-api.yaml (or pass a path/URL)
+npm run generate    # regenerate src/types.gen.ts and src/models.gen.ts from it
+npm run typecheck && npm run lint && npm test && npm run build
+```
+
+The SDK is generated from the published [OpenAPI spec](https://docs.pantechdynamics.com/openapi/public-api.yaml).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and how releases are made. Report security
+issues as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE).