@walkthru-earth/objex 1.2.0 → 1.3.0

package/dist/utils/connection-identity.js

@@ -0,0 +1,97 @@
+/**
+ * Canonical connection identity.
+ *
+ * Single source of truth for deciding when two connection configs point at
+ * the same bucket. Used by the connections store to deduplicate auto-detect,
+ * manual add, and edit flows, so one physical bucket never ends up with
+ * multiple competing local records.
+ *
+ * Identity rules, per provider:
+ *
+ *   azure  → (provider, endpoint, bucket)     endpoint carries the account
+ *   gcs    → (provider, bucket)               GCS bucket names are global
+ *   s3     → (provider, bucket, region)       AWS native: same bucket name
+ *                                             can exist in exactly one region,
+ *                                             but the region is load-bearing
+ *                                             for signing, so a paste with a
+ *                                             different region is a distinct
+ *                                             connection until the user merges
+ *   other  → (provider, endpoint, bucket)     r2, b2, minio, wasabi, storj,
+ *                                             digitalocean, contabo, hetzner,
+ *                                             linode, ovhcloud, custom
+ *
+ * Endpoint normalization is aggressive: scheme + host + non-default port +
+ * pathname, with trailing slashes and default ports stripped, host lowercased.
+ * That collapses the common trip hazards — http vs https, :443 vs empty,
+ * trailing slash drift, mixed case host.
+ */
+const DEFAULT_PORTS = {
+    'https:': '443',
+    'http:': '80'
+};
+/**
+ * Normalize an endpoint URL to a canonical form suitable for equality checks.
+ * Empty / whitespace-only input returns `''` (the "no endpoint" sentinel).
+ * Non-URL strings are lowercased and stripped of trailing slashes as a best
+ * effort so the comparison is still deterministic.
+ */
+export function normalizeEndpoint(raw) {
+    if (!raw)
+        return '';
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return '';
+    try {
+        const url = new URL(trimmed);
+        const scheme = url.protocol.toLowerCase();
+        const host = url.hostname.toLowerCase();
+        const defaultPort = DEFAULT_PORTS[scheme] ?? '';
+        const port = url.port && url.port !== defaultPort ? `:${url.port}` : '';
+        const path = url.pathname.replace(/\/+$/, '');
+        return `${scheme}//${host}${port}${path}`;
+    }
+    catch {
+        return trimmed.toLowerCase().replace(/\/+$/, '');
+    }
+}
+/** Collapse unknown / empty providers to `'s3'`; otherwise lowercase. */
+export function normalizeProvider(provider) {
+    if (!provider)
+        return 's3';
+    const p = provider.trim().toLowerCase();
+    if (!p || p === 'unknown')
+        return 's3';
+    return p;
+}
+/** Bucket names are case-sensitive on some backends, so preserve case. */
+function normalizeBucket(bucket) {
+    return (bucket ?? '').trim().replace(/^\/+|\/+$/g, '');
+}
+function normalizeRegion(region) {
+    return (region ?? '').trim().toLowerCase();
+}
+/**
+ * Produce a canonical key for a connection's identity. Two connection
+ * configs with the same identity key point at the same physical bucket.
+ * Returns `''` when the config is too incomplete to identify a bucket.
+ */
+export function connectionIdentityKey(input) {
+    const provider = normalizeProvider(input.provider);
+    const bucket = normalizeBucket(input.bucket);
+    if (!bucket)
+        return '';
+    const endpoint = normalizeEndpoint(input.endpoint);
+    const region = normalizeRegion(input.region);
+    if (provider === 'azure')
+        return `azure|${endpoint}|${bucket}`;
+    if (provider === 'gcs')
+        return `gcs|${bucket}`;
+    if (provider === 's3' && !endpoint)
+        return `s3|${bucket}|${region}`;
+    return `${provider}|${endpoint}|${bucket}`;
+}
+/** Convenience: true when both inputs share the same non-empty identity. */
+export function isSameConnectionIdentity(a, b) {
+    const key = connectionIdentityKey(a);
+    return key !== '' && key === connectionIdentityKey(b);
+}

package/dist/utils/host-detection.js

@@ -8,7 +8,7 @@
  * Also extracts `rootPrefix` when the app is hosted inside a subfolder.
  */
 import { buildProviderBaseUrl } from '../storage/providers.js';
-import { parseStorageUrl } from './storage-url.js';
+import { isKnownBucketHost, parseStorageUrl } from './storage-url.js';
 /**
  * Extract root prefix from pathname.
  * When hosted at `/subfolder/index.html` or `/subfolder/`, returns `subfolder/`.
@@ -32,6 +32,24 @@ function extractRootPrefix(pathname) {
 function buildBucketUrl(provider, endpoint, bucket, region) {
     return buildProviderBaseUrl((provider === 'unknown' ? 's3' : provider), endpoint, bucket, region || '');
 }
+/**
+ * Translate a `ParsedStorageUrl` into a `DetectedHost`. Returns null when the
+ * parser did not recognize a bucket or when the host is not a known provider
+ * pattern (prevents arbitrary custom endpoints from being auto-connected).
+ */
+function parsedToHost(parsed, host, rootPrefix) {
+    if (!parsed.bucket || !isKnownBucketHost(host))
+        return null;
+    const provider = parsed.provider === 'unknown' ? 's3' : parsed.provider;
+    return {
+        provider,
+        bucket: parsed.bucket,
+        region: parsed.region,
+        endpoint: parsed.endpoint,
+        rootPrefix,
+        bucketUrl: buildBucketUrl(parsed.provider, parsed.endpoint, parsed.bucket, parsed.region)
+    };
+}
 /**
  * Detect hosting bucket from current URL.
  * Returns null when no hosting bucket can be determined.
@@ -40,310 +58,38 @@ export function detectHostBucket() {
     if (typeof window === 'undefined')
         return null;
     const url = new URL(window.location.href);
-    const host = url.hostname;
-    // --- Priority 1: ?url= query parameter ---
+    // Priority 1: ?url= query parameter
     const urlParam = url.searchParams.get('url');
     if (urlParam) {
-        const parsed = parseStorageUrl(urlParam);
-        if (parsed.bucket) {
-            return {
-                provider: parsed.provider === 'unknown' ? 's3' : parsed.provider,
-                bucket: parsed.bucket,
-                region: parsed.region,
-                endpoint: parsed.endpoint,
-                rootPrefix: '',
-                bucketUrl: buildBucketUrl(parsed.provider, parsed.endpoint, parsed.bucket)
-            };
-        }
-    }
-    // --- Priority 2: Hostname pattern matching ---
-    const pathname = url.pathname;
-    // AWS S3 virtual-hosted: <bucket>.s3.<region>.amazonaws.com
-    const awsVhost = host.match(/^(.+)\.s3[.-]([a-z0-9-]+)\.amazonaws\.com$/);
-    if (awsVhost) {
-        return {
-            provider: 's3',
-            bucket: awsVhost[1],
-            region: awsVhost[2],
-            endpoint: '',
-            rootPrefix: extractRootPrefix(pathname),
-            bucketUrl: `https://s3.${awsVhost[2]}.amazonaws.com/${awsVhost[1]}`
-        };
-    }
-    // AWS S3 website hosting: <bucket>.s3-website-<region>.amazonaws.com or <bucket>.s3-website.<region>.amazonaws.com
-    const awsWebsite = host.match(/^(.+)\.s3-website[.-]([a-z0-9-]+)\.amazonaws\.com$/);
-    if (awsWebsite) {
-        return {
-            provider: 's3',
-            bucket: awsWebsite[1],
-            region: awsWebsite[2],
-            endpoint: '',
-            rootPrefix: extractRootPrefix(pathname),
-            bucketUrl: `https://s3.${awsWebsite[2]}.amazonaws.com/${awsWebsite[1]}`
-        };
-    }
-    // AWS S3 path-style: s3.<region>.amazonaws.com/<bucket>
-    const awsPath = host.match(/^s3[.-]([a-z0-9-]+)\.amazonaws\.com$/);
-    if (awsPath) {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        if (parts.length > 0) {
-            return {
-                provider: 's3',
-                bucket: parts[0],
-                region: awsPath[1],
-                endpoint: '',
-                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
-                bucketUrl: `https://s3.${awsPath[1]}.amazonaws.com/${parts[0]}`
-            };
-        }
-    }
-    // GCS: storage.googleapis.com/<bucket>
-    if (host === 'storage.googleapis.com') {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        if (parts.length > 0) {
-            return {
-                provider: 'gcs',
-                bucket: parts[0],
-                region: 'us',
-                endpoint: '',
-                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
-                bucketUrl: `https://storage.googleapis.com/${parts[0]}`
-            };
-        }
-    }
-    // GCS virtual-hosted: <bucket>.storage.googleapis.com
-    const gcsVhost = host.match(/^(.+)\.storage\.googleapis\.com$/);
-    if (gcsVhost) {
-        return {
-            provider: 'gcs',
-            bucket: gcsVhost[1],
-            region: 'us',
-            endpoint: '',
-            rootPrefix: extractRootPrefix(pathname),
-            bucketUrl: `https://storage.googleapis.com/${gcsVhost[1]}`
-        };
-    }
-    // Azure Static Website: <account>.z<N>.web.core.windows.net
-    const azureWeb = host.match(/^([a-z0-9]+)\.z\d+\.web\.core\.windows\.net$/);
-    if (azureWeb) {
-        return {
-            provider: 'azure',
-            bucket: '$web',
-            region: '',
-            endpoint: `https://${azureWeb[1]}.blob.core.windows.net`,
-            rootPrefix: extractRootPrefix(pathname),
-            bucketUrl: `https://${azureWeb[1]}.blob.core.windows.net/$web`
-        };
-    }
-    // Azure Blob: <account>.blob.core.windows.net/<container>
-    const azureBlob = host.match(/^([a-z0-9]+)\.blob\.core\.windows\.net$/);
-    if (azureBlob) {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        if (parts.length > 0) {
-            return {
-                provider: 'azure',
-                bucket: parts[0],
-                region: '',
-                endpoint: `https://${host}`,
-                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
-                bucketUrl: `https://${host}/${parts[0]}`
-            };
-        }
-    }
-    // R2 public: pub-<id>.r2.dev
-    const r2Public = host.match(/^(pub-[a-z0-9]+)\.r2\.dev$/);
-    if (r2Public) {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        return {
-            provider: 'r2',
-            bucket: parts[0] || r2Public[1],
-            region: 'auto',
-            endpoint: `https://${host}`,
-            rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
-            bucketUrl: `https://${host}`
-        };
-    }
-    // DigitalOcean Spaces: <bucket>.<region>.digitaloceanspaces.com
-    const doSpaces = host.match(/^(.+)\.([a-z0-9-]+)\.digitaloceanspaces\.com$/);
-    if (doSpaces) {
-        return {
-            provider: 'digitalocean',
-            bucket: doSpaces[1],
-            region: doSpaces[2],
-            endpoint: `https://${doSpaces[2]}.digitaloceanspaces.com`,
-            rootPrefix: extractRootPrefix(pathname),
-            bucketUrl: `https://${doSpaces[2]}.digitaloceanspaces.com/${doSpaces[1]}`
-        };
-    }
-    // DigitalOcean Spaces CDN: <bucket>.<region>.cdn.digitaloceanspaces.com
-    const doCdn = host.match(/^(.+)\.([a-z0-9-]+)\.cdn\.digitaloceanspaces\.com$/);
-    if (doCdn) {
-        return {
-            provider: 'digitalocean',
-            bucket: doCdn[1],
-            region: doCdn[2],
-            endpoint: `https://${doCdn[2]}.digitaloceanspaces.com`,
-            rootPrefix: extractRootPrefix(pathname),
-            bucketUrl: `https://${doCdn[2]}.digitaloceanspaces.com/${doCdn[1]}`
-        };
-    }
-    // Wasabi: s3.<region>.wasabisys.com/<bucket>
-    const wasabi = host.match(/^s3\.([a-z0-9-]+)\.wasabisys\.com$/);
-    if (wasabi) {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        if (parts.length > 0) {
-            return {
-                provider: 'wasabi',
-                bucket: parts[0],
-                region: wasabi[1],
-                endpoint: `https://${host}`,
-                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
-                bucketUrl: `https://${host}/${parts[0]}`
-            };
-        }
-    }
-    // B2 S3: <bucket>.s3.<region>.backblazeb2.com
-    const b2s3 = host.match(/^(.+)\.s3\.([a-z0-9-]+)\.backblazeb2\.com$/);
-    if (b2s3) {
-        return {
-            provider: 'b2',
-            bucket: b2s3[1],
-            region: b2s3[2],
-            endpoint: `https://s3.${b2s3[2]}.backblazeb2.com`,
-            rootPrefix: extractRootPrefix(pathname),
-            bucketUrl: `https://s3.${b2s3[2]}.backblazeb2.com/${b2s3[1]}`
-        };
-    }
-    // IBM COS: <bucket>.s3-web.<region>.cloud-object-storage.appdomain.cloud
-    const ibmCos = host.match(/^(.+)\.s3-web\.([a-z0-9-]+)\.cloud-object-storage\.appdomain\.cloud$/);
-    if (ibmCos) {
-        return {
-            provider: 's3',
-            bucket: ibmCos[1],
-            region: ibmCos[2],
-            endpoint: `https://s3.${ibmCos[2]}.cloud-object-storage.appdomain.cloud`,
-            rootPrefix: extractRootPrefix(pathname),
-            bucketUrl: `https://s3.${ibmCos[2]}.cloud-object-storage.appdomain.cloud/${ibmCos[1]}`
-        };
-    }
-    // Storj S3 gateway: gateway.storjshare.io/<bucket> (or gateway.<region>.storjshare.io)
-    const storjGateway = host.match(/^gateway\.(?:([a-z0-9]+)\.)?storjshare\.io$/);
-    if (storjGateway) {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        if (parts.length > 0) {
-            return {
-                provider: 'storj',
-                bucket: parts[0],
-                region: storjGateway[1] || 'us1',
-                endpoint: `${url.protocol}//${url.host}`,
-                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
-                bucketUrl: `${url.protocol}//${url.host}/${parts[0]}`
-            };
-        }
-    }
-    // Storj linksharing: link.storjshare.io/raw/<access>/<bucket>/...
-    const storjLink = host.match(/^link\.(?:([a-z0-9]+)\.)?storjshare\.io$/);
-    if (storjLink) {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        if (parts.length >= 3 && (parts[0] === 'raw' || parts[0] === 's')) {
-            return {
-                provider: 'storj',
-                bucket: parts[2],
-                region: storjLink[1] || 'us1',
-                endpoint: `${url.protocol}//${url.host}/${parts[0]}/${parts[1]}`,
-                rootPrefix: parts.length > 3 ? extractRootPrefix(`/${parts.slice(3).join('/')}`) : '',
-                bucketUrl: `${url.protocol}//${url.host}/${parts[0]}/${parts[1]}/${parts[2]}`
-            };
-        }
-    }
-    // Contabo: <region>.contabostorage.com/<bucket>
-    const contabo = host.match(/^([a-z0-9]+)\.contabostorage\.com$/);
-    if (contabo) {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        if (parts.length > 0) {
-            return {
-                provider: 'contabo',
-                bucket: parts[0],
-                region: contabo[1],
-                endpoint: `${url.protocol}//${url.host}`,
-                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
-                bucketUrl: `${url.protocol}//${url.host}/${parts[0]}`
-            };
+        try {
+            const paramUrl = new URL(urlParam);
+            const parsed = parseStorageUrl(urlParam);
+            const host = parsedToHost(parsed, paramUrl.hostname, '');
+            if (host)
+                return host;
         }
-    }
-    // Hetzner: <region>.your-objectstorage.com/<bucket>
-    const hetzner = host.match(/^([a-z0-9]+)\.your-objectstorage\.com$/);
-    if (hetzner) {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        if (parts.length > 0) {
-            return {
-                provider: 'hetzner',
-                bucket: parts[0],
-                region: hetzner[1],
-                endpoint: `${url.protocol}//${url.host}`,
-                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
-                bucketUrl: `${url.protocol}//${url.host}/${parts[0]}`
-            };
+        catch {
+            // Not a parseable URL, fall through to location-based detection.
         }
     }
-    // Linode / Akamai: <bucket>.<region>.linodeobjects.com or <region>.linodeobjects.com/<bucket>
-    const linodeVhost = host.match(/^(.+)\.([a-z0-9-]+)\.linodeobjects\.com$/);
-    if (linodeVhost) {
-        return {
-            provider: 'linode',
-            bucket: linodeVhost[1],
-            region: linodeVhost[2],
-            endpoint: `https://${linodeVhost[2]}.linodeobjects.com`,
-            rootPrefix: extractRootPrefix(pathname),
-            bucketUrl: `https://${linodeVhost[2]}.linodeobjects.com/${linodeVhost[1]}`
-        };
-    }
-    const linodePath = host.match(/^([a-z0-9-]+)\.linodeobjects\.com$/);
-    if (linodePath) {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        if (parts.length > 0) {
-            return {
-                provider: 'linode',
-                bucket: parts[0],
-                region: linodePath[1],
-                endpoint: `https://${url.host}`,
-                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
-                bucketUrl: `https://${url.host}/${parts[0]}`
-            };
-        }
-    }
-    // OVHcloud: s3.<region>.io.cloud.ovh.net/<bucket>
-    const ovh = host.match(/^s3\.([a-z0-9-]+)\.io\.cloud\.ovh\.(?:net|us)$/);
-    if (ovh) {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        if (parts.length > 0) {
-            return {
-                provider: 'ovhcloud',
-                bucket: parts[0],
-                region: ovh[1],
-                endpoint: `https://${url.host}`,
-                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
-                bucketUrl: `https://${url.host}/${parts[0]}`
-            };
-        }
-    }
-    // MinIO / localhost / private IPs
-    const isLocal = host === 'localhost' ||
-        host === '127.0.0.1' ||
-        host.startsWith('192.168.') ||
-        host.startsWith('10.');
-    if (isLocal) {
-        const parts = pathname.replace(/^\//, '').split('/').filter(Boolean);
-        if (parts.length > 0) {
-            return {
-                provider: 'minio',
-                bucket: parts[0],
-                region: 'us-east-1',
-                endpoint: `${url.protocol}//${url.host}`,
-                rootPrefix: parts.length > 1 ? extractRootPrefix(`/${parts.slice(1).join('/')}`) : '',
-                bucketUrl: `${url.protocol}//${url.host}/${parts[0]}`
-            };
-        }
-    }
-    return null;
+    // Priority 2: window.location pattern matching via the unified parser.
+    // `parseStorageUrl` extracts bucket + any remaining prefix from the
+    // current URL. The prefix is used as the in-bucket sub-folder the app
+    // should root into when auto-connecting.
+    const parsed = parseStorageUrl(window.location.href);
+    if (!parsed.bucket || !isKnownBucketHost(url.hostname))
+        return null;
+    // `rootPrefix` is the in-bucket sub-folder, possibly trailing with an
+    // `index.html` style filename, which `extractRootPrefix` strips.
+    const prefixPath = parsed.prefix ? `/${parsed.prefix}` : '';
+    const rootPrefix = extractRootPrefix(prefixPath || '/');
+    const provider = parsed.provider === 'unknown' ? 's3' : parsed.provider;
+    return {
+        provider,
+        bucket: parsed.bucket,
+        region: parsed.region,
+        endpoint: parsed.endpoint,
+        rootPrefix,
+        bucketUrl: buildBucketUrl(parsed.provider, parsed.endpoint, parsed.bucket, parsed.region)
+    };
 }

package/dist/utils/parquet-metadata.d.ts

@@ -20,11 +20,17 @@ export interface GeoParquetMeta {
 export interface ParquetFileMetadata {
     /** Total number of rows across all row groups. */
     rowCount: number;
-    /** Column schema (name + type). */
+    /** Column schema (name + type). Leaf columns only (structs flattened to children). */
     schema: {
         name: string;
         type: string;
     }[];
+    /**
+     * Top-level column names as written. Includes struct/group parents (e.g.
+     * `assets`, `bbox`) that `schema` flattens away. Required for stac-geoparquet
+     * detection, which looks up struct columns by their parent name.
+     */
+    topLevelColumns: string[];
     /** GeoParquet "geo" metadata if present. */
     geo: GeoParquetMeta | null;
     /** True when file has legacy GeoParquet metadata (schema_version 0.x without "version" field). */

package/dist/utils/parquet-metadata.js

@@ -114,6 +114,19 @@ export async function readParquetMetadata(url) {
         name: col.name,
         type: mapParquetType(col)
     }));
+    // Walk depth-first to collect top-level column names (including struct parents).
+    // hyparquet serializes the schema as a flat depth-first array where the root
+    // carries `num_children` and each group element claims the next N siblings.
+    const topLevelColumns = [];
+    const root = metadata.schema[0];
+    const rootChildren = root?.num_children ?? 0;
+    let cursor = 1;
+    for (let i = 0; i < rootChildren && cursor < metadata.schema.length; i++) {
+        const el = metadata.schema[cursor];
+        if (el?.name)
+            topLevelColumns.push(el.name);
+        cursor += countSubtree(metadata.schema, cursor);
+    }
     // GeoParquet "geo" key-value metadata
     let geo = null;
     let legacyGeoParquet = false;
@@ -167,7 +180,28 @@ export async function readParquetMetadata(url) {
             compression = [...codecs].join(', ');
         }
     }
-    return { rowCount, schema, geo, legacyGeoParquet, createdBy, numRowGroups, compression };
+    return {
+        rowCount,
+        schema,
+        topLevelColumns,
+        geo,
+        legacyGeoParquet,
+        createdBy,
+        numRowGroups,
+        compression
+    };
+}
+/** Count how many schema elements belong to the subtree rooted at `start` (inclusive). */
+function countSubtree(schema, start) {
+    const el = schema[start];
+    if (!el)
+        return 0;
+    const n = el.num_children ?? 0;
+    let cursor = start + 1;
+    for (let i = 0; i < n; i++) {
+        cursor += countSubtree(schema, cursor);
+    }
+    return cursor - start;
 }
 /**
  * Extract EPSG code from GeoParquet CRS metadata.

package/dist/utils/stac-geoparquet.d.ts

@@ -0,0 +1,90 @@
+/**
+ * stac-geoparquet helpers.
+ *
+ * Pure TypeScript, zero Svelte / DuckDB / deck.gl dependencies. Re-exported
+ * through `@walkthru-earth/objex-utils` so other projects can consume the
+ * detection + row-to-Item transforms without pulling the Svelte lib.
+ *
+ * The module is decoupled from WKB decoding: callers pass a `wkbParser`
+ * callback (the objex Svelte lib threads its `parseWKB`; other consumers
+ * can plug in `geoarrow-wasm`, `wkx`, or any other library).
+ */
+import type { StacAsset, StacItem } from './stac.js';
+/** Minimal schema column shape. Works with hyparquet, DuckDB, Arrow. */
+export interface StacGeoparquetSchemaColumn {
+    name: string;
+    type?: string;
+}
+/** Bbox in struct shape as produced by DuckDB's `bbox struct(xmin,ymin,xmax,ymax)`. */
+export interface StacBboxStruct {
+    xmin: number;
+    ymin: number;
+    xmax: number;
+    ymax: number;
+}
+/** Generic Record shape representing a single stac-geoparquet row after DuckDB decoding. */
+export type StacGeoparquetRow = Record<string, unknown>;
+export interface StacRowToItemOptions {
+    /**
+     * Decoder for the geometry column. Accepts a Uint8Array of WKB bytes and
+     * returns a GeoJSON geometry object (or null on failure).
+     *
+     * Consumers in the objex Svelte lib should pass `parseWKB` from
+     * `@walkthru-earth/objex-utils`. Other projects can use any WKB library.
+     */
+    wkbParser?: (bytes: Uint8Array) => unknown;
+    /**
+     * Column name holding the WKB bytes. Defaults to `'geom_wkb'` because the
+     * recommended SQL projection is `ST_AsWKB(geometry) AS geom_wkb`.
+     */
+    wkbColumn?: string;
+    /** Override the column holding the pre-decoded GeoJSON geometry, when available. */
+    geometryColumn?: string;
+}
+/** Columns every stac-geoparquet file MUST carry per the stac-geoparquet spec. */
+export declare const STAC_GEOPARQUET_REQUIRED_COLUMNS: readonly ["stac_version", "type", "geometry", "assets"];
+/**
+ * Detect stac-geoparquet by presence of the required STAC columns.
+ *
+ * Deliberately type-agnostic: some pipelines know the type (DuckDB DESCRIBE,
+ * Arrow Field), others only have the name list (hyparquet schema walk). The
+ * set of names is sufficient for routing.
+ */
+export declare function isStacGeoparquetSchema(schema: StacGeoparquetSchemaColumn[]): boolean;
+/**
+ * Flatten a DuckDB `struct(xmin,ymin,xmax,ymax)` bbox to the `[minX, minY, maxX, maxY]`
+ * array shape that STAC Items and deck.gl-geotiff MosaicLayer expect.
+ *
+ * Pass-through for arrays so callers that already have `[minX,minY,maxX,maxY]`
+ * shape (e.g. from a Feature's `bbox` field) don't need a separate path.
+ */
+export declare function flattenStacBbox(bbox: StacBboxStruct | number[] | null | undefined): [number, number, number, number] | null;
+/**
+ * Resolve a possibly-relative STAC asset href against the parquet file URL.
+ *
+ * `./foo.tif` or `foo.tif` → absolute against `baseUrl`. Absolute URLs
+ * (`http(s)://`, `s3://`, `gs://`, etc.) are returned unchanged.
+ */
+export declare function resolveStacAssetHref(href: string, baseUrl: string): string;
+/**
+ * Pick the "primary" asset from a STAC Item's `assets` map.
+ *
+ * Priority: caller-specified `preferredKeys` → `data` key → first asset with
+ * `roles` containing `'data'` → first asset. Returns `null` if the map is
+ * empty or not an object.
+ */
+export declare function pickStacPrimaryAsset(assets: Record<string, StacAsset> | null | undefined, preferredKeys?: readonly string[]): {
+    key: string;
+    asset: StacAsset;
+} | null;
+/**
+ * Convert one stac-geoparquet row into a standard STAC Item JSON object.
+ *
+ * Handles:
+ *   - `assets` named-struct flattening + relative href resolution
+ *   - `bbox` struct → `[minX, minY, maxX, maxY]` array
+ *   - Optional WKB geometry → GeoJSON via `opts.wkbParser`
+ *   - `datetime` → ISO string (passes through already-string values)
+ *   - Promotes `properties.*` columns (`proj:*`, `datetime`) onto `item.properties`
+ */
+export declare function stacRowToItem(row: StacGeoparquetRow, baseUrl: string, opts?: StacRowToItemOptions): StacItem;