astrospatial-services 0.0.0-stage → 0.1.0

package/LICENSE-COMMERCIAL.md

@@ -0,0 +1,19 @@
+Astrospatial Services Commercial Licensing
+
+Commercial use of Astrospatial Services requires a separate written agreement with
+the copyright holder.
+
+Examples of commercial use include, without limitation:
+
+- integration into proprietary software
+- use in internal business systems or business operations
+- paid services, hosted offerings, SaaS, or managed services
+- consulting deliverables transferred to a client
+- OEM, embedded, or bundled redistribution
+- use by or for a company, institution, contractor, or client in connection
+  with direct or indirect revenue generation
+
+Unless and until a commercial agreement is executed, no commercial rights are
+granted by this repository or package.
+
+Contact the copyright holder to discuss commercial licensing terms.

package/LICENSE.md

@@ -0,0 +1,49 @@
+# Astrospatial Services Licensing
+
+Copyright (C) Fabrizio Giordano
+
+Astrospatial Services is distributed under a dual-license model.
+
+You may use Astrospatial Services under either of the following licensing options.
+
+## 1. GNU Affero General Public License v3.0
+
+Astrospatial Services is available under the GNU Affero General Public License
+version 3 (`AGPL-3.0-only`).
+
+This is an open-source license and permits commercial and non-commercial use,
+modification, redistribution, and network-based use, subject to the terms and
+obligations of the AGPL-3.0.
+
+The complete license text is available in:
+
+`LICENSE-AGPL.md`
+
+## 2. Commercial license
+
+A separate commercial license is available for organizations or individuals
+that want to use Astrospatial Services under terms that do not impose the
+requirements of the AGPL-3.0.
+
+Typical commercial-license use cases include proprietary products, closed-source
+applications, SaaS offerings, embedded products, OEM redistribution, or other
+situations where AGPL-3.0 obligations are not suitable.
+
+See:
+
+`LICENSE-COMMERCIAL.md`
+
+for commercial licensing information.
+
+## Choosing a license
+
+You may choose either licensing track according to your requirements.
+
+Use of Astrospatial Services under the AGPL-3.0 does not require a commercial
+license, including for commercial activity, provided that the AGPL-3.0 terms
+are satisfied.
+
+The commercial license provides an alternative licensing path for proprietary
+or otherwise incompatible use cases.
+
+Third-party dependencies remain governed by their respective licenses.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# astrospatial-services
 
-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.
+Render-independent TypeScript services for scientific data access across astronomy, Earth observation and planetary applications.
+
+**Status:** 0.1.0-snapshot; foundation and CDS Sesame name resolution only. TAP and HiPS discovery are planned, **not implemented**.
+
+## Requirements
+
+Node.js >=22, npm, TypeScript 5.x. ESM package; browser-compatible APIs (`fetch`, `AbortSignal`) with no dependency on AstroViewer.
+
+## Development
+
+```sh
+npm ci
+npm test
+npm pack --dry-run
+```
+
+## Name resolution
+
+```ts
+import { SesameService } from 'astrospatial-services/astronomy/name-resolver';
+const resolver = new SesameService();
+const target = await resolver.resolve('M51'); // { name, raDeg, decDeg, resolver? } or null
+```
+
+`resolve()` returns `null` for an unresolved name. Transport, HTTP, timeout and malformed-response failures throw `ServiceError` with a `code`. Endpoint and transport are injectable; callers may pass an `AbortSignal`.
+
+The XML parser is a small, deliberately limited parser for Sesame's `Target/Resolver/jradeg/jdedeg` response. It is not a general-purpose XML parser; richer Sesame responses or VOTable will require a dedicated parser and fixtures.
+
+### Live integration
+
+```sh
+RUN_LIVE_TESTS=1 npm run test:live
+```
+
+Live tests require external CDS availability and are excluded from ordinary CI.
+
+## Roadmap
+
+- HiPS node discovery and `hipslist`/`properties` parsing, independent of AstroViewer's `HiPSDescriptor`.
+- TAP Sync/ADQL with typed tabular results, then TAP Async and VOTable metadata.
+- Later: STAC/OGC Earth observation and planetary/PDS discovery.
+
+## Licensing
+
+Dual-licensed under AGPL-3.0-only or a separate commercial license. See LICENSE.md.

package/lib-esm/astronomy/hips/HiPSNodeService.d.ts

@@ -0,0 +1,37 @@
+import { type HttpTransport } from "../../core/HttpTransport.js";
+export type HiPSMetadata = Record<string, string>;
+export interface HiPSSurveyEntry {
+    serviceUrl: string;
+    creatorDid?: string;
+    releaseDate?: string;
+    metadata: HiPSMetadata;
+}
+export interface HiPSProperties {
+    serviceUrl: string;
+    creatorDid?: string;
+    title?: string;
+    order?: number;
+    frame?: string;
+    tileFormats: string[];
+    metadata: HiPSMetadata;
+}
+export interface HiPSNodeServiceOptions {
+    transport?: HttpTransport;
+    timeoutMs?: number;
+}
+export interface HiPSRequestOptions {
+    signal?: AbortSignal;
+}
+/** Parse HiPS key=value lines; retain unknown keys and values containing '='. */
+export declare function parseHiPSMetadata(text: string): HiPSMetadata;
+/** Parse CDS-style hipslist records separated by blank lines. */
+export declare function parseHiPSList(text: string): HiPSSurveyEntry[];
+export declare function parseHiPSProperties(text: string, serviceUrl: string): HiPSProperties;
+/** HTTP-only HiPS discovery and properties, independent of rendering engines. */
+export declare class HiPSNodeService {
+    private readonly transport;
+    private readonly timeoutMs;
+    constructor(options?: HiPSNodeServiceOptions);
+    listSurveys(nodeUrl: string, options?: HiPSRequestOptions): Promise<HiPSSurveyEntry[]>;
+    getProperties(serviceUrl: string, options?: HiPSRequestOptions): Promise<HiPSProperties>;
+}

package/lib-esm/astronomy/hips/HiPSNodeService.js

@@ -0,0 +1,104 @@
+import { FetchHttpTransport } from "../../core/HttpTransport.js";
+import { ServiceError } from "../../core/ServiceError.js";
+/** Parse HiPS key=value lines; retain unknown keys and values containing '='. */
+export function parseHiPSMetadata(text) {
+    const metadata = {};
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const separator = line.indexOf('=');
+        if (separator < 0)
+            continue;
+        const key = line.slice(0, separator).trim();
+        if (!key)
+            continue;
+        metadata[key] = line.slice(separator + 1).trim();
+    }
+    return metadata;
+}
+/** Parse CDS-style hipslist records separated by blank lines. */
+export function parseHiPSList(text) {
+    if (typeof text !== 'string')
+        throw new TypeError('HiPS list must be text');
+    const blocks = text.split(/(?:\r?\n)[ \t]*(?:\r?\n)+/);
+    const entries = [];
+    for (const block of blocks) {
+        const metadata = parseHiPSMetadata(block);
+        const serviceUrl = metadata.hips_service_url;
+        if (!serviceUrl)
+            continue;
+        entries.push({
+            serviceUrl,
+            ...(metadata.creator_did ? { creatorDid: metadata.creator_did } : {}),
+            ...(metadata.hips_release_date ? { releaseDate: metadata.hips_release_date } : {}),
+            metadata,
+        });
+    }
+    return entries;
+}
+function normalizeHttpUrl(url, filename) {
+    const value = url.trim();
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new TypeError(`Invalid HiPS URL: ${url}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new TypeError('HiPS URL must use HTTP or HTTPS');
+    }
+    if (parsed.username || parsed.password)
+        throw new TypeError('HiPS URL must not contain credentials');
+    if (parsed.pathname.endsWith('/' + filename))
+        return parsed.toString();
+    if (parsed.search || parsed.hash)
+        throw new TypeError('HiPS base URL must not have query or fragment');
+    parsed.pathname = parsed.pathname.replace(/\/+$/, '') + '/' + filename;
+    return parsed.toString();
+}
+export function parseHiPSProperties(text, serviceUrl) {
+    const metadata = parseHiPSMetadata(text);
+    if (Object.keys(metadata).length === 0) {
+        throw new ServiceError('INVALID_RESPONSE', 'Empty or invalid HiPS properties');
+    }
+    const orderText = metadata.hips_order;
+    const order = orderText === undefined ? undefined : Number(orderText);
+    if (orderText !== undefined && (!Number.isInteger(order) || order < 0)) {
+        throw new ServiceError('INVALID_RESPONSE', 'Invalid hips_order');
+    }
+    return {
+        serviceUrl,
+        ...(metadata.creator_did ? { creatorDid: metadata.creator_did } : {}),
+        ...(metadata.obs_title ? { title: metadata.obs_title } : {}),
+        ...(order !== undefined ? { order } : {}),
+        ...(metadata.hips_frame ? { frame: metadata.hips_frame } : {}),
+        tileFormats: metadata.hips_tile_format?.split(/\s+/).filter(Boolean) ?? [],
+        metadata,
+    };
+}
+/** HTTP-only HiPS discovery and properties, independent of rendering engines. */
+export class HiPSNodeService {
+    transport;
+    timeoutMs;
+    constructor(options = {}) {
+        this.transport = options.transport ?? new FetchHttpTransport();
+        this.timeoutMs = options.timeoutMs ?? 10000;
+    }
+    async listSurveys(nodeUrl, options = {}) {
+        const url = normalizeHttpUrl(nodeUrl, 'hipslist');
+        const text = await this.transport.getText(url, { signal: options.signal, timeoutMs: this.timeoutMs });
+        const surveys = parseHiPSList(text);
+        if (surveys.length === 0 && text.trim()) {
+            throw new ServiceError('INVALID_RESPONSE', `No HiPS entries found at ${url}`);
+        }
+        return surveys;
+    }
+    async getProperties(serviceUrl, options = {}) {
+        const url = normalizeHttpUrl(serviceUrl, 'properties');
+        const text = await this.transport.getText(url, { signal: options.signal, timeoutMs: this.timeoutMs });
+        const base = url.slice(0, -'/properties'.length);
+        return parseHiPSProperties(text, base);
+    }
+}

package/lib-esm/astronomy/hips/index.d.ts

@@ -0,0 +1,2 @@
+export { HiPSNodeService, parseHiPSList, parseHiPSMetadata, parseHiPSProperties } from './HiPSNodeService.js';
+export type { HiPSMetadata, HiPSSurveyEntry, HiPSProperties, HiPSNodeServiceOptions, HiPSRequestOptions } from './HiPSNodeService.js';

package/lib-esm/astronomy/hips/index.js

@@ -0,0 +1 @@
+export { HiPSNodeService, parseHiPSList, parseHiPSMetadata, parseHiPSProperties } from './HiPSNodeService.js';

package/lib-esm/astronomy/name-resolver/SesameService.d.ts

@@ -0,0 +1,29 @@
+import { type HttpTransport } from '../../core/HttpTransport.js';
+export interface ResolvedTarget {
+    name: string;
+    raDeg: number;
+    decDeg: number;
+    resolver?: string;
+}
+export interface NameResolver {
+    resolve(name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ResolvedTarget | null>;
+}
+export interface SesameServiceOptions {
+    endpoint?: string;
+    timeoutMs?: number;
+    transport?: HttpTransport;
+}
+/** CDS Sesame XML resolver; coordinates are decimal degrees (ICRS/J2000 as supplied by CDS). */
+export declare class SesameService implements NameResolver {
+    private readonly endpoint;
+    private readonly timeoutMs;
+    private readonly transport;
+    constructor(options?: SesameServiceOptions);
+    resolve(name: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ResolvedTarget | null>;
+}
+/** Parse Sesame's <Target><Resolver><jradeg>/<jdedeg> XML without browser-only DOMParser. */
+export declare function parseSesameXml(xml: string, name: string): ResolvedTarget | null;

package/lib-esm/astronomy/name-resolver/SesameService.js

@@ -0,0 +1,45 @@
+import { FetchHttpTransport } from '../../core/HttpTransport.js';
+import { ServiceError } from '../../core/ServiceError.js';
+/** CDS Sesame XML resolver; coordinates are decimal degrees (ICRS/J2000 as supplied by CDS). */
+export class SesameService {
+    endpoint;
+    timeoutMs;
+    transport;
+    constructor(options = {}) {
+        this.endpoint = options.endpoint ?? 'https://cdsweb.u-strasbg.fr/cgi-bin/nph-sesame/-ox?';
+        this.timeoutMs = options.timeoutMs ?? 10000;
+        this.transport = options.transport ?? new FetchHttpTransport();
+    }
+    async resolve(name, options = {}) {
+        if (!name.trim())
+            throw new TypeError('Target name must not be empty');
+        const raw = await this.transport.getText(this.endpoint + encodeURIComponent(name.trim()), {
+            signal: options.signal,
+            timeoutMs: this.timeoutMs,
+        });
+        return parseSesameXml(raw, name.trim());
+    }
+}
+/** Parse Sesame's <Target><Resolver><jradeg>/<jdedeg> XML without browser-only DOMParser. */
+export function parseSesameXml(xml, name) {
+    if (!xml.trim() || !/<Sesame(?:\s|>)/i.test(xml)) {
+        throw new ServiceError('INVALID_RESPONSE', 'Unexpected Sesame XML response');
+    }
+    const targets = [...xml.matchAll(/<Target(?:\s[^>]*)?>([\s\S]*?)<\/Target>/gi)];
+    for (const target of targets) {
+        const resolvers = [...target[1].matchAll(/<Resolver(?:\s([^>]*))?>([\s\S]*?)<\/Resolver>/gi)];
+        for (const resolver of resolvers) {
+            const raText = resolver[2].match(/<jradeg(?:\s[^>]*)?>\s*([^<]+)\s*<\/jradeg>/i)?.[1];
+            const decText = resolver[2].match(/<jdedeg(?:\s[^>]*)?>\s*([^<]+)\s*<\/jdedeg>/i)?.[1];
+            if (raText === undefined || decText === undefined)
+                continue;
+            const raDeg = Number(raText.trim());
+            const decDeg = Number(decText.trim());
+            if (!Number.isFinite(raDeg) || !Number.isFinite(decDeg) || raDeg < 0 || raDeg >= 360 || decDeg < -90 || decDeg > 90)
+                continue;
+            const resolverName = resolver[1]?.match(/\bname\s*=\s*["']([^"']+)["']/i)?.[1];
+            return { name, raDeg, decDeg, ...(resolverName ? { resolver: resolverName } : {}) };
+        }
+    }
+    return null;
+}

package/lib-esm/astronomy/name-resolver/index.d.ts

@@ -0,0 +1,2 @@
+export { SesameService, parseSesameXml } from './SesameService.js';
+export type { NameResolver, ResolvedTarget, SesameServiceOptions } from './SesameService.js';

package/lib-esm/astronomy/name-resolver/index.js

@@ -0,0 +1 @@
+export { SesameService, parseSesameXml } from './SesameService.js';

package/lib-esm/astronomy/tap/TapMetadataAdapter.d.ts

@@ -0,0 +1,9 @@
+import { MetadataColumn } from "astrospatial-core/metadata";
+import type { TapColumn } from "./TapService.js";
+/**
+ * Convert TAP_SCHEMA column descriptions into shared metadata columns.
+ *
+ * TAP-specific attributes remain available in MetadataColumn.details.
+ * This function does not parse or convert query result values.
+ */
+export declare function tapColumnsToMetadata(columns: readonly TapColumn[]): MetadataColumn[];

package/lib-esm/astronomy/tap/TapMetadataAdapter.js

@@ -0,0 +1,64 @@
+import { ColumnType, MetadataColumn } from "astrospatial-core/metadata";
+function columnType(column) {
+    const ucd = column.ucd.trim().toLowerCase();
+    const datatype = column.datatype.trim().toLowerCase();
+    const ucdTerms = ucd.split(";").map((term) => term.trim());
+    const primaryUcd = ucdTerms[0];
+    const arraysize = column.arraysize.trim();
+    const isScalar = arraysize === "" || arraysize === "1";
+    const numericTypes = new Set([
+        "short",
+        "int",
+        "integer",
+        "long",
+        "float",
+        "double",
+        "unsignedbyte",
+    ]);
+    const isNumericScalar = numericTypes.has(datatype) && isScalar;
+    if (primaryUcd === "pos.eq.ra" && isNumericScalar) {
+        return ColumnType.GEOM_RA;
+    }
+    if (primaryUcd === "pos.eq.dec" && isNumericScalar) {
+        return ColumnType.GEOM_DEC;
+    }
+    if (primaryUcd === "pos.outline") {
+        return ColumnType.GEOM_FOOTPRINT;
+    }
+    if (primaryUcd === "meta.id" && ucdTerms.includes("meta.main")) {
+        return ColumnType.MAIN_NAME;
+    }
+    return isNumericScalar ? ColumnType.NUMBER : ColumnType.STRING;
+}
+/**
+ * Convert TAP_SCHEMA column descriptions into shared metadata columns.
+ *
+ * TAP-specific attributes remain available in MetadataColumn.details.
+ * This function does not parse or convert query result values.
+ */
+export function tapColumnsToMetadata(columns) {
+    return columns.map((column, index) => {
+        const details = new Map();
+        for (const key of [
+            "table_name",
+            "ucd",
+            "utype",
+            "datatype",
+            "arraysize",
+            "xtype",
+            "principal",
+            "indexed",
+            "std",
+        ]) {
+            details.set(key, column[key]);
+        }
+        return new MetadataColumn({
+            index,
+            name: column.column_name,
+            description: column.description,
+            unit: column.unit,
+            columnType: columnType(column),
+            details,
+        });
+    });
+}

package/lib-esm/astronomy/tap/TapService.d.ts

@@ -0,0 +1,80 @@
+import { type HttpTransport } from "../../core/HttpTransport.js";
+export type TapOutputFormat = "json" | "csv" | "votable" | (string & {});
+export interface TapServiceOptions {
+    endpoint: string;
+    transport?: HttpTransport;
+    timeoutMs?: number;
+}
+export interface TapSyncQuery {
+    adql: string;
+    format?: TapOutputFormat;
+    maxrec?: number;
+    signal?: AbortSignal;
+}
+export interface TapQueryResponse {
+    body: string;
+    status: number;
+    headers: Headers;
+    contentType: string | null;
+}
+export interface TapSchema {
+    schema_name: string;
+    description: string;
+    utype: string;
+}
+export interface TapTable {
+    schema_name: string;
+    table_name: string;
+    table_type: string;
+    description: string;
+    utype: string;
+}
+export interface TapColumn {
+    table_name: string;
+    column_name: string;
+    description: string;
+    unit: string;
+    ucd: string;
+    utype: string;
+    datatype: string;
+    arraysize: string;
+    xtype: string;
+    principal: string;
+    indexed: string;
+    std: string;
+}
+export interface TapCsvTable {
+    columns: string[];
+    rows: Record<string, string>[];
+}
+/** Parse RFC-style CSV with quoted commas, escaped quotes and embedded newlines. */
+export declare function parseTapCsvTable(csv: string): TapCsvTable;
+/**
+ * Parse TAP CSV and return data rows.
+ * Preserves the existing public API.
+ */
+export declare function parseTapCsv(csv: string): Record<string, string>[];
+/** TAP 1.x synchronous ADQL client. No rendering or backend dependency. */
+export declare class TapService {
+    private readonly baseUrl;
+    private readonly url;
+    private readonly transport;
+    private readonly timeoutMs;
+    constructor(options: TapServiceOptions);
+    /** Raw VOSI capabilities XML; parsing is intentionally left to the caller. */
+    getCapabilities(options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    private metadataRows;
+    listSchemas(options?: {
+        signal?: AbortSignal;
+    }): Promise<TapSchema[]>;
+    listTables(options?: {
+        schemaName?: string;
+        signal?: AbortSignal;
+    }): Promise<TapTable[]>;
+    listColumns(tableName: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<TapColumn[]>;
+    querySync(query: TapSyncQuery): Promise<TapQueryResponse>;
+}