@honua/react 0.0.20-alpha.0

package/control-plane/types.d.ts

@@ -0,0 +1,233 @@
+import type { Capability, Protocol, SourceDescriptor, SourceLocator } from "../contract/index.js";
+import type { HonuaCacheValidator } from "../core/cache-state.js";
+import type { QueryMethod } from "../core/types.js";
+import type { HonuaMapPackage } from "../runtime/index.js";
+export declare const HONUA_CONTROL_PLANE_BASE_PATH: "/api/v1/admin";
+/**
+ * Server-wide capability manifest path (`honua.capability_manifest.v1`). Sits
+ * outside the admin base path — the manifest describes the whole deployment,
+ * not an admin resource.
+ */
+export declare const HONUA_CAPABILITY_MANIFEST_PATH: "/api/v1/capabilities/manifest";
+export type HonuaControlPlaneCapability = "hosted-maps" | "map-packages" | "imports" | "api-tokens" | "workspaces" | "connections" | "sharing" | "capabilities" | "raw";
+/** Options for {@link HonuaControlPlaneClient.getCapabilityManifest}. */
+export interface HonuaCapabilityManifestOptions extends HonuaControlPlaneRequestOptions {
+    /** Optional environment (metadata snapshot) identifier to scope the manifest to. */
+    readonly environment?: string;
+    /** Optional workspace identifier to scope the manifest to. */
+    readonly workspaceId?: string;
+}
+export interface HonuaProblemDetails {
+    readonly type?: string;
+    readonly title?: string;
+    readonly status?: number;
+    readonly detail?: string;
+    readonly instance?: string;
+    readonly code?: string;
+    readonly errors?: Record<string, readonly string[]>;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaControlPlaneUnsupported {
+    readonly supported: false;
+    readonly capability: HonuaControlPlaneCapability;
+    readonly statusCode?: number;
+    readonly reason: string;
+    readonly problem?: HonuaProblemDetails;
+}
+export interface HonuaControlPlaneSuccess<T> {
+    readonly supported: true;
+    readonly value: T;
+}
+export type HonuaControlPlaneResult<T> = HonuaControlPlaneSuccess<T> | HonuaControlPlaneUnsupported;
+export interface HonuaControlPlaneRequestOptions {
+    readonly signal?: AbortSignal;
+    readonly headers?: HeadersInit;
+}
+export interface HonuaControlPlaneListOptions extends HonuaControlPlaneRequestOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly workspaceId?: string;
+    readonly q?: string;
+    readonly includeDeleted?: boolean;
+    readonly refresh?: boolean;
+    readonly validator?: HonuaCacheValidator;
+}
+export interface HonuaControlPlanePage<T> {
+    readonly items: readonly T[];
+    readonly pagination: {
+        readonly nextCursor?: string;
+        readonly previousCursor?: string;
+        readonly limit?: number;
+        readonly total?: number;
+    };
+    readonly validator?: HonuaCacheValidator;
+    readonly sourceUpdatedAt?: string;
+}
+export interface HonuaEntityValidators {
+    readonly etag?: string;
+    readonly lastModified?: string;
+}
+export interface HonuaHostedMapSummary extends HonuaEntityValidators {
+    readonly id: string;
+    readonly title: string;
+    readonly workspaceId?: string;
+    readonly packageId?: string;
+    readonly status?: "Draft" | "Publishing" | "Ready" | "Failed" | "Archived" | (string & {});
+    readonly visibility?: "private" | "workspace" | "public" | (string & {});
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly links?: HonuaControlPlaneLinks;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaHostedMap extends HonuaHostedMapSummary {
+    readonly description?: string;
+    readonly sourceDescriptors?: readonly HonuaControlPlaneSourceDescriptor[];
+    readonly mapPackage?: HonuaMapPackage;
+}
+export interface HonuaCreateHostedMapRequest {
+    readonly title: string;
+    readonly workspaceId?: string;
+    readonly description?: string;
+    readonly visibility?: "private" | "workspace" | "public" | (string & {});
+    readonly sourceDescriptors?: readonly HonuaControlPlaneSourceDescriptor[];
+    readonly mapPackage?: HonuaMapPackage;
+    readonly metadata?: Record<string, unknown>;
+}
+export type HonuaUpdateHostedMapRequest = Partial<HonuaCreateHostedMapRequest> & {
+    readonly ifMatch?: string;
+};
+export interface HonuaMapPackageSummary extends HonuaEntityValidators {
+    readonly id: string;
+    readonly mapPackageId?: string;
+    readonly title?: string;
+    readonly status?: string;
+    readonly mapId?: string;
+    readonly workspaceId?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly expiresAt?: string;
+    readonly links?: HonuaControlPlaneLinks;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaPublishMapPackageRequest {
+    readonly mapId?: string;
+    readonly workspaceId?: string;
+    readonly package: HonuaMapPackage;
+    readonly message?: string;
+    readonly ifMatch?: string;
+}
+export interface HonuaPublishMapPackageResponse extends HonuaEntityValidators {
+    readonly packageId: string;
+    readonly mapPackage?: HonuaMapPackage;
+    readonly job?: HonuaControlPlaneJob;
+    readonly links?: HonuaControlPlaneLinks;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaControlPlaneSourceDescriptor {
+    readonly id: string;
+    readonly protocol: Protocol;
+    readonly locator: SourceLocator;
+    readonly capabilities: readonly Capability[];
+    readonly schema?: SourceDescriptor["schema"];
+    readonly analytics?: SourceDescriptor["analytics"];
+    readonly attribution?: string;
+}
+export interface HonuaImportCreateRequest {
+    readonly sourceKind: string;
+    readonly sourceUrl?: string;
+    readonly workspaceId?: string;
+    readonly connectionId?: string;
+    readonly title?: string;
+    readonly dryRun?: boolean;
+    readonly options?: Record<string, unknown>;
+}
+export type HonuaControlPlaneJobStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled" | (string & {});
+export interface HonuaControlPlaneJob extends HonuaEntityValidators {
+    readonly id: string;
+    readonly type?: "import" | "publish" | (string & {});
+    readonly status: HonuaControlPlaneJobStatus;
+    readonly progress?: {
+        readonly completed?: number;
+        readonly total?: number;
+        readonly message?: string;
+    };
+    readonly result?: unknown;
+    readonly problem?: HonuaProblemDetails;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly links?: HonuaControlPlaneLinks;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaApiTokenCreateRequest {
+    readonly name: string;
+    readonly workspaceId?: string;
+    readonly scopes?: readonly string[];
+    readonly expiresAt?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface HonuaApiToken extends HonuaEntityValidators {
+    readonly id: string;
+    readonly name: string;
+    readonly workspaceId?: string;
+    readonly scopes?: readonly string[];
+    readonly status?: "active" | "revoked" | "expired" | (string & {});
+    readonly prefix?: string;
+    readonly createdAt?: string;
+    readonly expiresAt?: string;
+    readonly lastUsedAt?: string;
+    readonly value?: string;
+    readonly secret?: string;
+    readonly token?: string;
+    readonly oneTimeReveal?: string;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaWorkspaceSummary extends HonuaEntityValidators {
+    readonly id: string;
+    readonly name: string;
+    readonly slug?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaConnectionSummary extends HonuaEntityValidators {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly workspaceId?: string;
+    readonly status?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly value?: string;
+    readonly secret?: string;
+    readonly password?: string;
+    readonly token?: string;
+    readonly [extra: string]: unknown;
+}
+export interface HonuaShareRequest {
+    readonly visibility: "private" | "workspace" | "public" | (string & {});
+    readonly principals?: ReadonlyArray<{
+        readonly type: "user" | "group" | "workspace" | (string & {});
+        readonly id: string;
+    }>;
+    readonly ifMatch?: string;
+}
+export interface HonuaShareResponse extends HonuaEntityValidators {
+    readonly id: string;
+    readonly visibility: string;
+    readonly principals?: HonuaShareRequest["principals"];
+    readonly [extra: string]: unknown;
+}
+export interface HonuaControlPlaneLinks {
+    readonly self?: string;
+    readonly mapPackage?: string;
+    readonly sourceDescriptor?: string;
+    readonly job?: string;
+    readonly [rel: string]: string | undefined;
+}
+export interface HonuaControlPlaneRawRequest extends HonuaControlPlaneRequestOptions {
+    readonly method?: QueryMethod;
+    readonly path: string;
+    readonly body?: unknown;
+    readonly okStatuses?: readonly number[];
+}
+//# sourceMappingURL=types.d.ts.map

package/control-plane/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/control-plane/types.ts"],"names":[],"mappings":"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"}

package/control-plane/types.js

@@ -0,0 +1,7 @@
+export const HONUA_CONTROL_PLANE_BASE_PATH = "/api/v1/admin";
+/**
+ * Server-wide capability manifest path (`honua.capability_manifest.v1`). Sits
+ * outside the admin base path — the manifest describes the whole deployment,
+ * not an admin resource.
+ */
+export const HONUA_CAPABILITY_MANIFEST_PATH = "/api/v1/capabilities/manifest";

package/core/batch.d.ts

@@ -0,0 +1,37 @@
+import type { HonuaClient } from "./client.js";
+import type { HonuaQueryResponse, MapLayerQueryRequest, QueryFeaturesRequest } from "./types.js";
+/** A single query item in a batch. */
+export interface BatchQueryItem {
+    /** When `"map-layer"`, calls `client.queryMapLayer()`; default is `"feature"`. */
+    type?: "feature" | "map-layer";
+    /** The query request payload. */
+    request: QueryFeaturesRequest | MapLayerQueryRequest;
+    /** Optional label to identify this query in the results. */
+    label?: string;
+}
+/** The result of a single query within a batch. */
+export interface BatchQueryResult {
+    /** The label from the corresponding `BatchQueryItem`, if provided. */
+    label?: string;
+    /** The successful query response, or `undefined` if the query failed. */
+    response?: HonuaQueryResponse;
+    /** The error thrown by the query, or `undefined` if the query succeeded. */
+    error?: Error;
+}
+/** Options for controlling batch query execution. */
+export interface BatchQueryOptions {
+    /** Maximum number of concurrent queries. Default: `5`. */
+    concurrency?: number;
+    /** An `AbortSignal` that, when aborted, skips all remaining unstarted queries. */
+    signal?: AbortSignal;
+}
+/**
+ * Execute multiple queries in parallel with bounded concurrency.
+ *
+ * Results are returned in the same order as the input `items`.
+ * Each result contains either a `response` (on success) or an `error` (on failure).
+ * If an `AbortSignal` is provided and aborted, remaining unstarted queries are
+ * skipped and their results will have an `error` set to an `AbortError`.
+ */
+export declare function batchQuery(client: HonuaClient, items: readonly BatchQueryItem[], options?: BatchQueryOptions): Promise<BatchQueryResult[]>;
+//# sourceMappingURL=batch.d.ts.map

package/core/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../src/core/batch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEjG,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,IAAI,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IAC/B,iCAAiC;IACjC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IACrD,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiF7B"}

package/core/batch.js

@@ -0,0 +1,79 @@
+import { HonuaAbortError } from "./errors.js";
+/**
+ * Execute multiple queries in parallel with bounded concurrency.
+ *
+ * Results are returned in the same order as the input `items`.
+ * Each result contains either a `response` (on success) or an `error` (on failure).
+ * If an `AbortSignal` is provided and aborted, remaining unstarted queries are
+ * skipped and their results will have an `error` set to an `AbortError`.
+ */
+export async function batchQuery(client, items, options) {
+    const concurrency = Math.max(1, options?.concurrency ?? 5);
+    const signal = options?.signal;
+    const results = new Array(items.length);
+    // Simple semaphore: track how many queries are currently in-flight.
+    let running = 0;
+    const queue = [];
+    function release() {
+        running--;
+        const next = queue.shift();
+        if (next) {
+            next();
+        }
+    }
+    function acquire() {
+        if (running < concurrency) {
+            running++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            queue.push(() => {
+                running++;
+                resolve();
+            });
+        });
+    }
+    const promises = [];
+    for (let i = 0; i < items.length; i++) {
+        const index = i;
+        const item = items[index];
+        const task = async () => {
+            // Check abort before acquiring a semaphore slot.
+            if (signal?.aborted) {
+                results[index] = {
+                    label: item.label,
+                    error: new HonuaAbortError("Batch query aborted before completion."),
+                };
+                return;
+            }
+            await acquire();
+            // Check abort again after acquiring the slot.
+            if (signal?.aborted) {
+                release();
+                results[index] = {
+                    label: item.label,
+                    error: new HonuaAbortError("Batch query aborted before completion."),
+                };
+                return;
+            }
+            try {
+                const response = item.type === "map-layer"
+                    ? await client.queryMapLayer(item.request)
+                    : await client.queryFeatures(item.request);
+                results[index] = { label: item.label, response };
+            }
+            catch (err) {
+                results[index] = {
+                    label: item.label,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                };
+            }
+            finally {
+                release();
+            }
+        };
+        promises.push(task());
+    }
+    await Promise.all(promises);
+    return results;
+}

package/core/cache-state.d.ts

@@ -0,0 +1,79 @@
+export type HonuaCacheScope = "metadata" | "materialized-result";
+export type HonuaCacheStatus = "hit" | "miss" | "stale" | "refreshed" | "bypass";
+export type HonuaCacheReadMode = "default" | "bypass";
+export interface HonuaCacheValidator {
+    readonly etag?: string;
+    readonly lastModified?: string;
+}
+export interface HonuaCacheState {
+    readonly scope: HonuaCacheScope;
+    readonly status: HonuaCacheStatus;
+    readonly keyFingerprint: string;
+    readonly ageMs?: number;
+    readonly ttlMs?: number;
+    readonly staleIfErrorMs?: number;
+    readonly revalidatedAt?: string;
+    readonly sourceUpdatedAt?: string;
+    readonly validator?: HonuaCacheValidator;
+    readonly invalidationReason?: string;
+    readonly refreshErrorId?: string;
+}
+export interface HonuaMetadataRequestOptions {
+    readonly signal?: AbortSignal;
+    /**
+     * Revalidate even when an SDK-local metadata entry is present. Adapters send
+     * conditional validators when available and report `refreshed` on success.
+     */
+    readonly refresh?: boolean;
+    /**
+     * `default` reads and writes the adapter metadata cache. `bypass` skips cache
+     * lookup and write-through for endpoints that support SDK-local caching.
+     */
+    readonly cache?: HonuaCacheReadMode;
+    /**
+     * Allow a cached metadata entry to be returned as `stale` when refresh fails.
+     * Defaults to `true`; ignored when no cached metadata entry exists.
+     */
+    readonly staleIfError?: boolean;
+    /** Optional freshness budget surfaced to callers in `HonuaCacheState`. */
+    readonly ttlMs?: number;
+    /** Optional stale fallback window surfaced to callers in `HonuaCacheState`. */
+    readonly staleIfErrorMs?: number;
+}
+export interface NormalizedHonuaMetadataRequestOptions {
+    readonly signal?: AbortSignal;
+    readonly refresh: boolean;
+    readonly cache: HonuaCacheReadMode;
+    readonly staleIfError: boolean;
+    readonly ttlMs?: number;
+    readonly staleIfErrorMs?: number;
+}
+export declare const HONUA_DEFAULT_METADATA_CACHE_TTL_MS: number;
+export declare const HONUA_DEFAULT_METADATA_STALE_IF_ERROR_MS: number;
+export interface HonuaCacheStateInit {
+    readonly scope: HonuaCacheScope;
+    readonly status: HonuaCacheStatus;
+    readonly keyFingerprint: string;
+    readonly ageMs?: number;
+    readonly ttlMs?: number;
+    readonly staleIfErrorMs?: number;
+    readonly revalidatedAt?: string;
+    readonly sourceUpdatedAt?: string;
+    readonly validator?: HonuaCacheValidator;
+    readonly invalidationReason?: string;
+    readonly refreshErrorId?: string;
+}
+export declare function createHonuaCacheState(init: HonuaCacheStateInit): HonuaCacheState;
+export declare function normalizeHonuaMetadataRequestOptions(options?: HonuaMetadataRequestOptions): NormalizedHonuaMetadataRequestOptions;
+export declare function isHonuaCacheEntryFresh(cachedAtMs: number, now: number, ttlMs: number | undefined): boolean;
+export declare function isHonuaCacheStatus(value: unknown): value is HonuaCacheStatus;
+export declare function honuaCacheValidatorFromHeaders(headers: Headers): HonuaCacheValidator | undefined;
+export declare function honuaMetadataRequestHeaders(options: {
+    readonly accept?: string;
+    readonly refresh?: boolean;
+    readonly bypass?: boolean;
+    readonly validator?: HonuaCacheValidator;
+}): Record<string, string>;
+export declare function withHonuaCacheState<T>(value: T, cache: HonuaCacheState): T;
+export declare function withoutHonuaCacheState<T>(value: T): T;
+//# sourceMappingURL=cache-state.d.ts.map

package/core/cache-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-state.d.ts","sourceRoot":"","sources":["../../../src/core/cache-state.ts"],"names":[],"mappings":"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"}

package/core/cache-state.js

@@ -0,0 +1,87 @@
+export const HONUA_DEFAULT_METADATA_CACHE_TTL_MS = 5 * 60 * 1000;
+export const HONUA_DEFAULT_METADATA_STALE_IF_ERROR_MS = 60 * 60 * 1000;
+export function createHonuaCacheState(init) {
+    return {
+        scope: init.scope,
+        status: init.status,
+        keyFingerprint: init.keyFingerprint,
+        ...(init.ageMs !== undefined ? { ageMs: Math.max(0, Math.trunc(init.ageMs)) } : {}),
+        ...(init.ttlMs !== undefined ? { ttlMs: Math.max(0, Math.trunc(init.ttlMs)) } : {}),
+        ...(init.staleIfErrorMs !== undefined ? { staleIfErrorMs: Math.max(0, Math.trunc(init.staleIfErrorMs)) } : {}),
+        ...(init.revalidatedAt ? { revalidatedAt: init.revalidatedAt } : {}),
+        ...(init.sourceUpdatedAt ? { sourceUpdatedAt: init.sourceUpdatedAt } : {}),
+        ...(hasHonuaCacheValidator(init.validator) ? { validator: init.validator } : {}),
+        ...(init.invalidationReason ? { invalidationReason: init.invalidationReason } : {}),
+        ...(init.refreshErrorId ? { refreshErrorId: init.refreshErrorId } : {}),
+    };
+}
+export function normalizeHonuaMetadataRequestOptions(options = {}) {
+    const ttlMs = normalizeNonNegativeInteger(options.ttlMs) ?? HONUA_DEFAULT_METADATA_CACHE_TTL_MS;
+    const staleIfErrorMs = normalizeNonNegativeInteger(options.staleIfErrorMs) ?? HONUA_DEFAULT_METADATA_STALE_IF_ERROR_MS;
+    return {
+        ...(options.signal ? { signal: options.signal } : {}),
+        refresh: options.refresh === true,
+        cache: options.cache === "bypass" ? "bypass" : "default",
+        staleIfError: options.staleIfError !== false,
+        ttlMs,
+        staleIfErrorMs,
+    };
+}
+export function isHonuaCacheEntryFresh(cachedAtMs, now, ttlMs) {
+    return ttlMs === undefined || Math.max(0, now - cachedAtMs) < ttlMs;
+}
+export function isHonuaCacheStatus(value) {
+    return value === "hit" || value === "miss" || value === "stale" || value === "refreshed" || value === "bypass";
+}
+export function honuaCacheValidatorFromHeaders(headers) {
+    const etag = headers.get("etag") ?? undefined;
+    const lastModified = headers.get("last-modified") ?? undefined;
+    return hasHonuaCacheValidator({ etag, lastModified })
+        ? { ...(etag ? { etag } : {}), ...(lastModified ? { lastModified } : {}) }
+        : undefined;
+}
+export function honuaMetadataRequestHeaders(options) {
+    const headers = {
+        Accept: options.accept ?? "application/json",
+    };
+    if (options.bypass) {
+        headers["Cache-Control"] = "no-store";
+        headers.Pragma = "no-cache";
+        return headers;
+    }
+    if (options.refresh) {
+        headers["Cache-Control"] = "no-cache";
+        if (options.validator?.etag) {
+            headers["If-None-Match"] = options.validator.etag;
+        }
+        if (options.validator?.lastModified) {
+            headers["If-Modified-Since"] = options.validator.lastModified;
+        }
+    }
+    return headers;
+}
+export function withHonuaCacheState(value, cache) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return value;
+    }
+    return {
+        ...value,
+        cache,
+    };
+}
+export function withoutHonuaCacheState(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return value;
+    }
+    const { cache: _cache, ...rest } = value;
+    return rest;
+}
+function hasHonuaCacheValidator(value) {
+    return Boolean(value?.etag || value?.lastModified);
+}
+function normalizeNonNegativeInteger(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return undefined;
+    }
+    return Math.max(0, Math.trunc(value));
+}