@surfiran/public-api-client 0.27.0 → 0.29.0

package/README.md

@@ -1,6 +1,6 @@
 # Public API Client
 
-Zero-runtime-dependency TypeScript types and fetch client for SURFIRAN Public API V1. The checked-in package-local contract snapshot is OpenAPI `v0.17.0`.
+Zero-runtime-dependency TypeScript types and fetch client for SURFIRAN Public API V1. The checked-in package-local contract snapshot is OpenAPI `v0.18.0`.
 
 Repository: `SURFIRAN/surfiran-public-api-client`
 
@@ -18,11 +18,11 @@ The repository split and production cutover are complete. This repository is the
 
 `contract/public-api-v1.yaml` is the package-local immutable snapshot used for generation. `contract/provenance.json` records its source identity, immutable source revision, checksums, and, for standalone releases, the exact API artifact identity.
 
-The checked-in `0.26.0` snapshot and provenance come from the `SURFIRAN/surfiran-crm-api` main-branch artifact `public-api-contract-c7ed3f7bf7930c540f07d8f6c47d47fba4f024ae-35233930079-1`. Published `0.20.0` and earlier keep their historical provenance, which may still reference the former monorepo owner or path. Do not rewrite an already published package version solely to rename historical provenance.
+The checked-in `0.29.0` snapshot and provenance come from the `SURFIRAN/surfiran-crm-api` main-branch release `public-api-contract/ad9252578477406f13cb7db52e4f12c32715b00e-36233980383-1`. Published `0.20.0` and earlier keep their historical provenance, which may still reference the former monorepo owner or path. Do not rewrite an already published package version solely to rename historical provenance.
 
-New client versions must consume an immutable reviewed contract artifact produced by a successful `SURFIRAN/surfiran-crm-api` main-branch CI run. The artifact is bound to the API source commit, GitHub Actions run identity, source ref/event, contract version, and checksum. Pull-request artifacts are verification evidence only and are not valid release inputs. This repository must never read another repository's private working tree at build time.
+New client versions must consume the exact immutable GitHub Release assets produced from a successful `SURFIRAN/surfiran-crm-api` main-branch CI run. The release tag is `public-api-contract/<source SHA>-<run ID>-<attempt>` and contains only `public-api-v1.yaml` and `manifest.json`. Publication verifies the immutable release and both GitHub release attestations, the tag SHA, final successful source run, asset digests, manifest identity, and checked-in snapshot bytes. If any check is unavailable, publication stops. Pull-request artifacts are verification evidence only and are not valid release inputs. This repository must never read another repository's private working tree at build time.
 
-Generated client source is never hand-edited.
+`src/generated/public-api-v1.ts` is generated from the checked-in snapshot; `src/client.ts` and `src/types.ts` are maintained in this repository against that reviewed contract. Never hand-edit generated source.
 
 ## Boundary
 
@@ -65,9 +65,9 @@ Generation is deterministic: stable ordering and formatting, LF newlines, no mac
 
 A new contract update must:
 
-1. use the exact immutable artifact from a successful API run on `refs/heads/main` triggered by `push` or `workflow_dispatch`;
+1. use the exact immutable release assets from a successful API run on `refs/heads/main` triggered by `push` or `workflow_dispatch`;
 2. make a reviewed package version change before rewriting contract provenance;
-3. run `sync:api-contract-artifact` with the exact API commit, run ID, and run attempt;
+3. verify/download the release assets, then run `sync:api-contract-artifact` with the exact API commit, run ID, and run attempt;
 4. update `contract/public-api-v1.yaml` and `contract/provenance.json` together;
 5. regenerate the client;
 6. pass artifact verification, package verification, reproducibility, tests, typecheck, and build;
@@ -83,7 +83,9 @@ Do not duplicate the endpoint list here; the pinned OpenAPI snapshot and generat
 
 ## Publication and rollback
 
-Publication is manual and repository-local through [public-api-client-publish.yml](.github/workflows/public-api-client-publish.yml). It runs on `main` only with explicit publication authorization and `publish_confirm=PUBLISH`. A future version must be bound to an exact reviewed API contract artifact, pass package/reproducibility checks and publication preflight, create release provenance, and provide an exact previous rollback version. Missing or unverifiable artifact provenance blocks publication. The workflow defines required inputs and the download/verification sequence.
+Routine package CI runs on the non-production Linux `ci-worker` pool. Manual publication uses the dedicated trusted `package-publish` runner and never occupies `surfdmc-prod-deploy`; package and cross-repository artifact credentials do not move to Home or general CI workers.
+
+Publication is manual and repository-local through [public-api-client-publish.yml](.github/workflows/public-api-client-publish.yml). It runs on `main` only with explicit publication authorization and `publish_confirm=PUBLISH`. A future version must be bound to an exact reviewed API contract release, pass package/reproducibility checks and publication preflight, create release provenance, and provide an exact previous rollback version. The workflow uses `PUBLIC_API_CONTRACT_READ_TOKEN` to read the private immutable API release and a separate `PUBLIC_API_CLIENT_RELEASE_SETTINGS_READ_TOKEN` with scoped Administration:read to confirm immutable Releases are enabled for this client repository. Before publishing to npmjs.org, it creates or exactly reuses an immutable client release `public-api-client/v<package version>` containing the packed tarball and provenance JSON. It marks the evidence release as non-latest and verifies its asset digests, source tag SHA, and GitHub release attestations. Retries must reproduce the same bytes, including the explicit generation timestamp. Missing or unverifiable release or publication evidence blocks npm publication; the workflow does not use Actions artifact storage for these gates.
 
 Published versions are immutable. Rollback means pinning consumers to the previous verified exact package version. Package publication never deploys a consumer, changes API runtime behavior, applies a database migration, or authorizes production data/configuration access.
 
@@ -92,6 +94,6 @@ Published versions are immutable. Rollback means pinning consumers to the previo
 - This README owns local setup, contract synchronization, CI, publication, and rollback guidance.
 - [AGENTS.md](AGENTS.md) owns agent operating instructions.
 - [Repository boundaries and documentation governance](https://github.com/SURFIRAN/surfiran-crm-api/blob/main/docs/architecture/REPOSITORY_BOUNDARIES.md) own shared architecture and current system state.
-- [Contract snapshot](contract/public-api-v1.yaml) and [provenance](contract/provenance.json) are immutable evidence for `0.26.0`, not current API ownership authorities.
+- [Contract snapshot](contract/public-api-v1.yaml) and [provenance](contract/provenance.json) are immutable evidence for `0.29.0`, not current API ownership authorities.
 
 Update existing guidance instead of creating duplicate contract or publication authorities. Preserve the historical snapshot, provenance, and generated bytes until a reviewed new package version imports a verified API artifact.

package/dist/client.d.ts

@@ -4,9 +4,7 @@ export type PublicApiClientOptions = {
     fetchImpl?: typeof fetch;
     requestId?: string;
     /**
-     * Bounds every request issued by this client. Defaults to 10000ms, matching
-     * the existing AbortController-based timeout precedent in
-     * server/services/webhookDispatcher.ts.
+     * Bounds every request issued by this client. Defaults to 10000ms.
      */
     timeoutMs?: number;
 };

package/dist/client.js

@@ -1,5 +1,20 @@
 const DEFAULT_TIMEOUT_MS = 10000;
-const trimTrailingSlash = (value) => value.replace(/\/+$/, '');
+/**
+ * Trims trailing slashes without a regular expression.
+ *
+ * `/\/+$/` has a candidate start at every slash, so a base URL ending in a
+ * long run of them was quadratic to reject (CodeQL js/polynomial-redos). This
+ * is a published client library: the base URL is whatever a consumer passes,
+ * and a library has no say in that. Scanning backwards is linear and says the
+ * same thing.
+ */
+const SLASH = 47;
+const trimTrailingSlash = (value) => {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === SLASH)
+        end -= 1;
+    return value.slice(0, end);
+};
 const isAbortError = (err) => err instanceof Error && err.name === 'AbortError';
 const toTimeoutResult = (status, requestId) => ({
     ok: false,
@@ -130,6 +145,8 @@ const toSearchResultsQueryString = (params) => {
         search.set('limit', String(params.limit));
     if (params.type)
         search.set('type', params.type);
+    if (params.locale)
+        search.set('locale', params.locale);
     return `?${search.toString()}`;
 };
 const toTravelKnowledgeQueryString = (params) => {

package/dist/types.d.ts

@@ -1002,6 +1002,18 @@ export type PublicSearchResultItem = {
     slug: string;
     path: string;
     summary: string | null;
+    /**
+     * Present only when a non-English locale was explicitly requested. Locale of
+     * the displayed label, from approved field provenance; `en` means the English
+     * source is displayed as a fallback (always the case for destinations).
+     */
+    labelSourceLocale?: PublicContentLocale;
+    /**
+     * Present only when a non-English locale was explicitly requested. Locale of
+     * the displayed summary, from approved field provenance; null when `summary`
+     * is null, and `en` when the English source is displayed as a fallback.
+     */
+    summarySourceLocale?: PublicContentLocale | null;
 };
 export type PublicSearchResultGroup = {
     type: 'tour' | 'destination';
@@ -1566,7 +1578,7 @@ export type ListPublicToursParams = {
     locale?: PublicContentLocale;
 };
 /** Locales the public content contract will resolve translations for. */
-export type PublicContentLocale = 'en' | 'de' | 'fr' | 'es' | 'it' | 'fa' | 'ar';
+export type PublicContentLocale = 'en' | 'de' | 'fr' | 'tr' | 'ru' | 'es' | 'it' | 'fa' | 'ar';
 export type GetPublicTourParams = {
     /** See ListPublicToursParams['locale']. */
     locale?: PublicContentLocale;
@@ -1623,6 +1635,8 @@ export type GetPublicSearchResultsParams = {
     /** Maximum items per group. 1 through 25; defaults to 10 server-side. Group totals still report every match. */
     limit?: number;
     type?: 'tour' | 'destination';
+    /** Published tour copy locale; omitted or en keeps the English results. */
+    locale?: PublicContentLocale;
 };
 export type ListPublicTourCategoriesParams = {
     limit?: number;

package/dist/types.js

@@ -1,3 +1,3 @@
-// TypeScript interfaces aligned with server/openapi/public-api-v1.yaml v0.10.0
+// Hand-maintained public API types; generated contract types live in src/generated/public-api-v1.ts.
 // Zero runtime code. Types only.
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surfiran/public-api-client",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "TypeScript types and client for SURFIRAN CRM Public API V1",
   "type": "module",
   "engines": {