@speleodb/api 0.1.0 → 0.2.0

package/README.md

@@ -75,8 +75,11 @@ silently omitting an update. See the
 `onUploadProgress` or `onUploadComplete` selects the browser XHR transport. The
 completion callback means request bytes have been uploaded; the server response
 may still be pending. Without these callbacks, requests use fetch. XHR rejects
-cookie omission and redirect-refusal policies it cannot enforce; use fetch for
-those operations. Callback failures do not change the HTTP result.
+cookie omission and redirect-refusal policies it cannot enforce. The XHR adapter
+also rejects `responsePolicy: 'status-first-json'` because it waits for the
+complete response body before inspecting status. Use fetch for those operations;
+the adapter never silently discards upload callbacks by switching transports.
+Callback failures do not change the HTTP result.
 
 ## Native and custom transports
 
@@ -133,7 +136,7 @@ schema.
 
 `bun run test` uses Vitest with Istanbul runtime coverage. A schema-derived
 loopback HTTP matrix exercises all 322 canonical operations, 525 generated
-request variants and 1,145 declared status/media combinations. It verifies
+request variants and 1,148 declared status/media combinations. It verifies
 request bytes, complete response metadata, decoding and unexpected responses.
 Focused tests cover cancellation, streaming, redirects, credentials, forms, XHR
 adapter events and generation safety. CI verifies generation, strict types,

package/docs/maintenance.md

@@ -46,7 +46,7 @@ runtime calls use generated TypeScript and do not download the schema.
 
 Change endpoint behavior, serializer annotations and contract tests in the web
 repository first. Its
-[API contract documentation](https://github.com/OpenSpeleo/SpeleoDB/blob/9b55e7c706947c2a4443110400375730e761bd26/docs/api-contract.md)
+[API contract documentation](https://github.com/OpenSpeleo/SpeleoDB/blob/93b445c7c5c7d69823a849806ea05b78058edec1/docs/api-contract.md)
 describes route inventory, allauth and OGC composition, error/media auditing and
 backend verification. Legacy v1 is intentionally excluded from this SDK.
 
@@ -233,7 +233,7 @@ hash-verifying source loader used by generation. It independently derives the
 operation, parameter, request-media and response-status/media inventory.
 `tests/generated-contract.test.ts` sends every generated callable through the
 public SDK and real fetch to an owned loopback HTTP server. Currently this means
-322 canonical operations, 525 request-media callables and 1,145 declared
+322 canonical operations, 525 request-media callables and 1,148 declared
 status/media cases. Each callable is checked against the entire canonical
 response metadata, not only the response selected for its request test.
 Undeclared statuses and media are tested for every operation as well.
@@ -322,11 +322,16 @@ generator upgrades.
 
 Browser upload tests distinguish progress, upload completion and response
 completion. XHR cannot enforce cookie omission or redirect refusal and must
-reject those policy combinations. Native adapters retain their own transport and
-device verification: ordinary TypeScript tests cannot prove cookie isolation
-inside an iOS/Android HTTP stack or cancellation on physical devices. In mobile,
-retain GIS status-before-body behavior and existing session/offline persistence
-regressions.
+reject those policy combinations. Our XHR adapter waits for the complete
+response before inspecting its status, so it also rejects
+`responsePolicy: 'status-first-json'` before constructing or sending a request.
+Keep regressions for explicit XHR selection and both upload callbacks with an
+untimed client: denial bodies must never silently become an indefinite wait. Do
+not fall back to fetch while silently dropping upload observers. Native adapters
+retain their own transport and device verification: ordinary TypeScript tests
+cannot prove cookie isolation inside an iOS/Android HTTP stack or cancellation
+on physical devices. In mobile, retain GIS status-before-body behavior and
+existing session/offline persistence regressions.
 
 The public generated options argument remains optional due to the fetch
 generator's signature, but an ApiClient is required at runtime. Do not introduce
@@ -363,6 +368,24 @@ operations or optional fields can be a minor release; behavior-preserving fixes
 can be patches. While the package is `0.x`, communicate breaking changes clearly
 and use a new minor version rather than quietly shipping them as a patch.
 
+### Migrating from 0.1.x to 0.2.0
+
+Cylinder installation creation now requires `project` in JSON, multipart and
+URL-encoded inputs, matching the backend's non-null project association. Include
+the existing project identifier when creating an installation; PUT/PATCH
+continue to allow omission to preserve the current association. Downloads at a
+specified revision now recognize JSON 400, 422 and 500 responses as documented
+results. Narrow the response by `kind` and `status` as usual. The XHR adapter
+now rejects `status-first-json` before sending; use fetch without upload
+observers when that response policy is required.
+
+These corrections require the 0.2.0 minor release because creation inputs are
+stricter. Update the exact package pin and standalone lock in each consumer,
+then run its own types, tests and build against the published package. The web
+backend remains the sole schema owner.
+
+### Release coordination
+
 The SDK version in `package.json` is independent of the backend version in
 OpenAPI's `info.version`. Never edit the backend YAML to bump the SDK version;
 the source record must continue identifying the reviewed producer bytes.
@@ -406,7 +429,7 @@ bun pm pack --destination "$archive_dir" --ignore-scripts
 mkdir "$archive_dir/consumer"
 cd "$archive_dir/consumer"
 printf '{"name":"sdk-smoke","private":true,"type":"module"}\n' > package.json
-bun add "$archive_dir/speleodb-api-0.1.0.tgz"
+bun add "$archive_dir/speleodb-api-0.2.0.tgz"
 bun add --dev typescript@6.0.3
 cat > smoke.ts <<'TS'
 import { createApiClient, v2ProjectsList } from '@speleodb/api';
@@ -485,8 +508,8 @@ export or hash mismatch before the publish job can run.
 After the required tests and repository-local prek checks pass, inspect the
 reviewed archive and commit the same source and documentation. When publication
 and Git actions are authorized, push the reviewed SDK commit and its
-`v<package.json version>` tag to its own upstream. For version `0.1.0`, the tag
-must be `v0.1.0`; the workflow rejects a mismatch. The publish job waits for
+`v<package.json version>` tag to its own upstream. For version `0.2.0`, the tag
+must be `v0.2.0`; the workflow rejects a mismatch. The publish job waits for
 `verify`, performs its own frozen install and build, and runs
 `npm publish --access public` from that tagged checkout. It packages the tagged
 files itself; the local archive is the reviewed candidate, not a separate
@@ -496,7 +519,7 @@ Wait for the tag workflow's successful publish job, then query the actual
 registry version:
 
 ```sh
-bun pm view @speleodb/api@0.1.0 name version dist.integrity
+bun pm view @speleodb/api@0.2.0 name version dist.integrity
 ```
 
 Use the actual release version. Inspect the published archive's file list,

package/openapi-source.json

@@ -1,4 +1,4 @@
 {
-  "revision": "9b55e7c706947c2a4443110400375730e761bd26",
-  "sha256": "c5b25a601e9ffcc18fcc165e695a5390cd6bdf496bbe4ee05ffcd190d2e7ee58"
+  "revision": "93b445c7c5c7d69823a849806ea05b78058edec1",
+  "sha256": "0074e12e23591cf0cbcdd6208c8d5df1989d09014e50ee22a38602c3d99f5a51"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speleodb/api",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/generated/models/cylinderInstallCreateRequestRequest.ts

@@ -9,7 +9,7 @@ import type { CylinderInstallCreateRequestRequestUnitSystem } from "./cylinderIn
  */
 export interface CylinderInstallCreateRequestRequest {
   cylinder: string;
-  project?: string;
+  project: string;
   /** Station latitude coordinate */
   latitude: string | number;
   /** Station longitude coordinate */

package/src/generated/models/index.ts

@@ -1292,8 +1292,11 @@ export * from "./v2ProjectsDownloadRetrieveByFormat403";
 export * from "./v2ProjectsDownloadRetrieveByFormat404";
 export * from "./v2ProjectsDownloadRetrieveByFormat422";
 export * from "./v2ProjectsDownloadRetrieveByFormat500";
+export * from "./v2ProjectsDownloadRetrieveByFormatAtHash400";
 export * from "./v2ProjectsDownloadRetrieveByFormatAtHash403";
 export * from "./v2ProjectsDownloadRetrieveByFormatAtHash404";
+export * from "./v2ProjectsDownloadRetrieveByFormatAtHash422";
+export * from "./v2ProjectsDownloadRetrieveByFormatAtHash500";
 export * from "./v2ProjectsExplorationLeadsCreateWithFormData400";
 export * from "./v2ProjectsExplorationLeadsCreateWithFormData403";
 export * from "./v2ProjectsExplorationLeadsCreateWithFormData404";

package/src/generated/models/v2CylinderInstallsCreateBodyOne.ts

@@ -9,7 +9,7 @@ import type { V2CylinderInstallsCreateBodyOneUnitSystem } from "./v2CylinderInst
  */
 export type V2CylinderInstallsCreateBodyOne = {
   cylinder: string;
-  project?: string;
+  project: string;
   /** Station latitude coordinate */
   latitude: string | number;
   /** Station longitude coordinate */

package/src/generated/models/v2CylinderInstallsCreateBodyThree.ts

@@ -9,7 +9,7 @@ import type { V2CylinderInstallsCreateBodyThreeUnitSystem } from "./v2CylinderIn
  */
 export type V2CylinderInstallsCreateBodyThree = {
   cylinder: string;
-  project?: string;
+  project: string;
   /** Station latitude coordinate */
   latitude: string | number;
   /** Station longitude coordinate */

package/src/generated/models/v2CylinderInstallsCreateBodyTwo.ts

@@ -9,7 +9,7 @@ import type { V2CylinderInstallsCreateBodyTwoUnitSystem } from "./v2CylinderInst
  */
 export type V2CylinderInstallsCreateBodyTwo = {
   cylinder: string;
-  project?: string;
+  project: string;
   /** Station latitude coordinate */
   latitude: string | number;
   /** Station longitude coordinate */

package/src/generated/models/v2ProjectsDownloadRetrieveByFormatAtHash400.ts

@@ -0,0 +1,15 @@
+/**
+ * Generated by Orval 8.43.0 from OpenAPI.yaml. Do not edit.
+ */
+
+export type V2ProjectsDownloadRetrieveByFormatAtHash400 =
+  | { [key: string]: string | string[] }
+  | {
+      error: string;
+    }
+  | {
+      detail: string;
+    }
+  | {
+      errors: { [key: string]: unknown } | string[];
+    };

package/src/generated/models/v2ProjectsDownloadRetrieveByFormatAtHash422.ts

@@ -0,0 +1,15 @@
+/**
+ * Generated by Orval 8.43.0 from OpenAPI.yaml. Do not edit.
+ */
+
+export type V2ProjectsDownloadRetrieveByFormatAtHash422 =
+  | { [key: string]: string | string[] }
+  | {
+      error: string;
+    }
+  | {
+      detail: string;
+    }
+  | {
+      errors: { [key: string]: unknown } | string[];
+    };

package/src/generated/models/v2ProjectsDownloadRetrieveByFormatAtHash500.ts

@@ -0,0 +1,15 @@
+/**
+ * Generated by Orval 8.43.0 from OpenAPI.yaml. Do not edit.
+ */
+
+export type V2ProjectsDownloadRetrieveByFormatAtHash500 =
+  | { [key: string]: string | string[] }
+  | {
+      error: string;
+    }
+  | {
+      detail: string;
+    }
+  | {
+      errors: { [key: string]: unknown } | string[];
+    };

package/src/generated/operations.ts

@@ -896,8 +896,11 @@ import type {
   V2ProjectsDownloadRetrieveByFormat404,
   V2ProjectsDownloadRetrieveByFormat422,
   V2ProjectsDownloadRetrieveByFormat500,
+  V2ProjectsDownloadRetrieveByFormatAtHash400,
   V2ProjectsDownloadRetrieveByFormatAtHash403,
   V2ProjectsDownloadRetrieveByFormatAtHash404,
+  V2ProjectsDownloadRetrieveByFormatAtHash422,
+  V2ProjectsDownloadRetrieveByFormatAtHash500,
   V2ProjectsExplorationLeadsCreateWithFormData400,
   V2ProjectsExplorationLeadsCreateWithFormData403,
   V2ProjectsExplorationLeadsCreateWithFormData404,
@@ -19308,6 +19311,11 @@ export type v2ProjectsDownloadRetrieveByFormatAtHashResponse200 = {
   status: 200;
 };
 
+export type v2ProjectsDownloadRetrieveByFormatAtHashResponse400 = {
+  data: V2ProjectsDownloadRetrieveByFormatAtHash400;
+  status: 400;
+};
+
 export type v2ProjectsDownloadRetrieveByFormatAtHashResponse403 = {
   data: V2ProjectsDownloadRetrieveByFormatAtHash403;
   status: 403;
@@ -19318,13 +19326,26 @@ export type v2ProjectsDownloadRetrieveByFormatAtHashResponse404 = {
   status: 404;
 };
 
+export type v2ProjectsDownloadRetrieveByFormatAtHashResponse422 = {
+  data: V2ProjectsDownloadRetrieveByFormatAtHash422;
+  status: 422;
+};
+
+export type v2ProjectsDownloadRetrieveByFormatAtHashResponse500 = {
+  data: V2ProjectsDownloadRetrieveByFormatAtHash500;
+  status: 500;
+};
+
 export type v2ProjectsDownloadRetrieveByFormatAtHashResponseSuccess =
   v2ProjectsDownloadRetrieveByFormatAtHashResponse200 & {
     headers: Headers;
   };
 export type v2ProjectsDownloadRetrieveByFormatAtHashResponseError = (
+  | v2ProjectsDownloadRetrieveByFormatAtHashResponse400
   | v2ProjectsDownloadRetrieveByFormatAtHashResponse403
   | v2ProjectsDownloadRetrieveByFormatAtHashResponse404
+  | v2ProjectsDownloadRetrieveByFormatAtHashResponse422
+  | v2ProjectsDownloadRetrieveByFormatAtHashResponse500
 ) & {
   headers: Headers;
 };
@@ -19357,8 +19378,11 @@ export const v2ProjectsDownloadRetrieveByFormatAtHash = (
         operationId: "v2_projects_download_retrieve_by_format_at_hash",
         responses: {
           "200": { content: { "application/octet-stream": "blob" } },
+          "400": { content: { "application/json": "json" } },
           "403": { content: { "application/json": "json" } },
           "404": { content: { "application/json": "json" } },
+          "422": { content: { "application/json": "json" } },
+          "500": { content: { "application/json": "json" } },
         },
       },
       ...options,

package/src/runtime/browser.ts

@@ -46,6 +46,13 @@ export function xhrTransport(
       ),
     );
   }
+  if (request.responsePolicy === "status-first-json") {
+    return Promise.reject(
+      new TypeError(
+        "The XHR adapter does not support status-first responses. Use the fetch transport.",
+      ),
+    );
+  }
   return new Promise((resolve, reject) => {
     request.signal.throwIfAborted();
     const xhr = new XMLHttpRequest();