@printhive/api 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+Initial partner-production client for server-side integrations such as Printie. Version 0.1.0 covers uploads and model reads only, including source inspection polling and source-file listing. Preparation methods (#4764) and order methods (#4631) will come in later versions.
+
+- Upload immutable 3MF sources with external IDs and idempotency keys.
+- Read sources, wait for inspection, look up models, and iterate source files.
+- Expose typed API restrictions, bounded safe retries, timeouts, and cancellation.
+- Generate types from a committed, drift-checked partner-production OpenAPI snapshot.
+
+Coverage is limited to `/v1/partner-production/`. Future releases can register more route plugins and widen the snapshot prefix filter without replacing the generation pipeline. They must add explicit resource methods and tests before claiming broader REST API coverage.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HyperFocus LLC
+
+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,80 @@
-# Temporary Holding Version
+# @printhive/api
 
-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.
+A TypeScript client for Print Hive's partner-production REST API. Version 0.1.0 has zero runtime dependencies and uses global `fetch`. It supports Node 20+, Bun, and Deno with npm compatibility. File paths require the runtime's Node filesystem compatibility. ESM, CommonJS, and TypeScript declarations ship together.
+
+Version 0.1.0 covers uploads and model reads only, including source inspection polling and source-file listing. Preparation methods (#4764) and order methods (#4631) will come in later versions.
+
+Partner API keys belong on your server. Never bundle a key into a browser, mobile app, or other distributed client. Printie's browser calls Printie's backend; that backend calls Print Hive.
+
+## Upload a Printie design
+
+Install `@printhive/api` after its first npm release. Before release, build and pack this workspace for local installation.
+
+```ts
+import { PrintHive } from "@printhive/api";
+
+const hive = new PrintHive({ apiKey: process.env.PRINTHIVE_API_KEY! });
+const source = await hive.partnerSources.upload({
+  file: "/srv/designs/project.3mf",
+  filename: "project.3mf",
+  externalId: "printie:design-1234",
+  idempotencyKey: "printie:design-1234:revision-1",
+});
+const settled = await hive.partnerSources.waitUntilSettled(
+  source.sourceVersionId,
+  {
+    intervalMs: 1000,
+    timeoutMs: 120_000,
+  }
+);
+if (settled.status === "ready") {
+  console.log(settled.inspection);
+} else {
+  console.error(settled.error.code, settled.error.limit);
+}
+```
+
+The key needs `production:upload` and `production:read` scopes. The organization must have partner source intake enabled. `ready` means inspection completed; it does not authorize printing or establish printer compatibility.
+
+## Client options and resources
+
+`new PrintHive({ apiKey, baseUrl?, fetch?, timeoutMs?, maxRetries? })` defaults to `https://api.printhiv3d.com`, global `fetch`, 30 seconds per request attempt, and two retries. `baseUrl` can include a reverse-proxy path prefix. Redirects fail to prevent credentials moving to another origin. Missing, blank, or invalid header values for `apiKey` throw `TypeError` during construction.
+
+`partnerSources.upload` accepts a filesystem path, Buffer, Uint8Array, or `ReadableStream<Uint8Array>`. Streams require an explicit byte `size`. Every upload sends `Content-Length` and a raw `model/3mf` body. Byte inputs are copied and path inputs are read into memory before sending. Upload returns the source fields plus `idempotencyKey`. When omitted, the client generates that key once per call. Persist a caller-supplied key before the first call when retries must survive process restarts. Use a new key when the bytes or binding change. An optional `modelId` binds to an existing model.
+
+`partnerSources.get(sourceId)` returns one typed source. `partnerSources.waitUntilSettled(sourceId, { intervalMs?, timeoutMs?, signal? })` resolves on `ready` or `failed`. Its default total polling deadline is 120 seconds; cancellation stops active reads and delays.
+
+`models.findByExternalId(externalId)` returns the bound model and latest source. `models.listSourceFiles(modelId)` is an async iterator over sources across cursor pages.
+
+```ts
+const model = await hive.models.findByExternalId("printie:design-1234");
+for await (const source of hive.models.listSourceFiles(model.modelId)) {
+  console.log(source.sourceVersionId, source.status);
+}
+```
+
+## Handle failures and retries
+
+`PrintHiveApiError` exposes HTTP `status`, the response's `error` as `code`, optional `limit` with `name`, `max`, and `observed`, `retryAfterMs`, and `requestId`. Its optional `body` exposes the validated error envelope, preserving additional fields as JSON values for callers to narrow. Invalid envelopes leave `body` undefined. Error messages omit response bodies and credentials. `PrintHiveNetworkError.reason` distinguishes `network`, `timeout`, and `aborted` failures.
+
+The API can answer `411 content_length_required`, `413 upload_too_large`, `429 upload_capacity_reached`, `409 external_id_conflict`, or `409 idempotency_conflict`. Inspection failures resolve through the source's `failed` status and include their own error and optional restriction limit.
+
+Only 429, 503, and network failures retry. GET requests are idempotent. Upload retries retain their idempotency key and require replayable bytes or a path. One-shot streams never retry. Timeouts and caller aborts never retry. Retries use exponential backoff with jitter and wait at least `Retry-After`, supporting both seconds and HTTP dates. If `Retry-After` exceeds 60 seconds, the client throws the API error with `retryAfterMs` so the caller can schedule the retry. It never retries before that delay. `maxRetries: 0` disables retries. Request timeouts apply per attempt; polling also has a total deadline.
+
+## Coverage and contract maintenance
+
+Version 0.1.0 covers only uploads, source reads and polling, external-id model lookup, and source-file listing under `/v1/partner-production/`. It offers no generic request method for other routes.
+
+`apps/api/scripts/export-openapi.ts` builds a schema-only Fastify app from the real partner route plugin, without listening, worker startup, database calls, or queue startup. It uses stub environment values. This intentionally exports authenticated partner routes directly. The Swagger UI's public-operation filter would remove them, and generic error enrichment would lose partner restriction details.
+
+`bun run generate` filters that export by the prefix list in `scripts/contracts.mjs`, commits `openapi.json`, and generates TypeScript types and standalone response validators. AJV compiles the validators during development; the build bundles their small runtime helpers. `openapi-typescript` is a development dependency because it generates OpenAPI 3 union types without adding runtime dependencies. `bun run check:drift` reexports and compares the snapshot. Types and standalone validators regenerate in ignored `.temp` build output on every check. `bun run test` builds the distribution and runs its HTTP tests against `dist`, including in the release workflow. `api-client-check.yml` also runs when API or client sources change, so drift checks do not depend on Turbo selecting the client as affected.
+
+To backfill more API capabilities, register their existing route plugins in the schema app and widen the prefix list. The snapshot and generation pipeline stay the same. Add resource methods and behavior tests for those routes before advertising coverage. Build API workspace dependencies first with `bun run build --filter='@hiv3d/api^...'` from the repository root.
+
+Run `bun run build`, `bun run check-types`, and `bun run test` in this package. The integration test skips by default. To read a source from an owned loopback API, set `PRINTHIVE_LOCAL_API_KEY`, `PRINTHIVE_LOCAL_SOURCE_ID`, and optionally `PRINTHIVE_LOCAL_API_URL`.
+
+## Release
+
+The manual `api-client-publish.yml` workflow builds, verifies, checks npm version availability, and publishes with `npm publish --access public` using `NPM_TOKEN`. It never runs on push. The `@printhive` npm organization must exist before the first release. Creating it and dispatching a release are maintainer actions.
+
+Provenance is intentionally disabled because the source repository is private. It can be enabled later through a matching public source mirror and its publishing workflow. The package omits a repository field pointing at the private monorepo.