@nextera.one/tps-standard 0.5.0 → 0.5.2

package/dist/index.d.ts

@@ -2,32 +2,79 @@
  * TPS: Temporal Positioning System
  * The Universal Protocol for Space-Time Coordinates.
  * @packageDocumentation
- * @version 0.4.2
- * @license MIT
+ * @version 0.5.0
+ * @license Apache-2.0
  * @copyright 2026 TPS Standards Working Group
+ *
+ * v0.5.0 Changes:
+ * - Added Actor anchor (A:) for provenance tracking
+ * - Added Signature (!) for cryptographic verification
+ * - Added structural anchors (bldg, floor, room, zone)
+ * - Added geospatial cell systems (S2, H3, Plus Code, what3words)
+ */
+export declare const DefaultCalendars: {
+    readonly TPS: "tps";
+    readonly GREG: "greg";
+    readonly HIJ: "hij";
+    readonly JUL: "jul";
+    readonly HOLO: "holo";
+    readonly UNIX: "unix";
+};
+/**
+ * Specifies the direction of the time-component hierarchy when serializing or
+ * deserializing a TPS string.  The default is `'descending'` (millennium → … →
+ * second), but `'ascending'` produces the reverse order.
  */
-export type CalendarCode = 'greg' | 'hij' | 'jul' | 'holo' | 'unix';
+export declare enum TimeOrder {
+    DESC = "desc",
+    ASC = "asc"
+}
 export interface TPSComponents {
-    calendar: CalendarCode;
-    millennium?: number;
-    century?: number;
-    year?: number;
-    month?: number;
-    day?: number;
-    hour?: number;
-    minute?: number;
-    second?: number;
+    calendar: string;
+    millennium: number;
+    century: number;
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    /** Sub-second precision (0–999).  Encoded as the last `m` token. */
+    millisecond: number;
     unixSeconds?: number;
     latitude?: number;
     longitude?: number;
     altitude?: number;
+    /** Google S2 cell ID (hierarchical, prefix-searchable) */
+    s2Cell?: string;
+    /** Uber H3 cell ID (hexagonal grid) */
+    h3Cell?: string;
+    /** Open Location Code / Plus Code */
+    plusCode?: string;
+    /** what3words address (e.g. "filled.count.soap") */
+    what3words?: string;
+    /** Physical building identifier */
+    building?: string;
+    /** Vertical division (level) */
+    floor?: string;
+    /** Enclosed space identifier */
+    room?: string;
+    /** Logical area within building */
+    zone?: string;
+    /** Raw pre-@ space anchor (e.g. adm:city:SA:riyadh, node:api-1, net:ip4:203.0.113.10) */
+    spaceAnchor?: string;
     /** Technical missing data (e.g. server log without GPS) */
     isUnknownLocation?: boolean;
     /** Removed for legal/security reasons (e.g. GDPR) */
     isRedactedLocation?: boolean;
     /** Masked by user preference (e.g. "Don't show my location") */
     isHiddenLocation?: boolean;
+    /** Actor anchor - identifies observer/witness (e.g. "did:web:sensor.example.com", "node:gateway-01") */
+    actor?: string;
+    /** Verification hash appended to time (e.g. "sha256:8f3e2a...") */
+    signature?: string;
     extensions?: Record<string, string>;
+    order?: TimeOrder;
 }
 /**
  * Interface for Calendar Driver plugins.
@@ -80,30 +127,30 @@ export interface TPSComponents {
  */
 export interface CalendarDriver {
     /** The calendar code this driver handles (e.g., 'hij', 'jul'). */
-    readonly code: CalendarCode;
+    readonly code: string;
     /**
      * Human-readable name for this calendar (optional).
      * @example "Hijri (Islamic)"
      */
     readonly name?: string;
     /**
-     * Converts a Gregorian Date to this calendar's components.
+     * Converts a Date to this calendar's components.
      * @param date - The Gregorian Date object.
      * @returns Partial TPS components for year, month, day, etc.
      */
-    fromGregorian(date: Date): Partial<TPSComponents>;
+    getComponentsFromDate(date: Date): Partial<TPSComponents>;
     /**
-     * Converts this calendar's components to a Gregorian Date.
+     * Converts this calendar's components to a Date.
      * @param components - Partial TPS components (year, month, day, etc.).
      * @returns A JavaScript Date object.
      */
-    toGregorian(components: Partial<TPSComponents>): Date;
+    getDateFromComponents(components: Partial<TPSComponents>): Date;
     /**
      * Generates a TPS time string for this calendar from a Date.
      * @param date - The Gregorian Date object.
-     * @returns A TPS time string (e.g., "T:hij.y1447.M07.d21...").
+     * @returns A TPS time string (e.g., "T:hij.y1447.m07.d21...").
      */
-    fromDate(date: Date): string;
+    getFromDate(date: Date): string;
     /**
      * Parse a calendar-specific date string into TPS components.
      * This allows drivers to handle native date formats from external libraries.
@@ -121,7 +168,7 @@ export interface CalendarDriver {
      * driver.parseDate('1447-07-21 14:30:00'); // → { year: 1447, month: 7, day: 21, hour: 14, ... }
      * ```
      */
-    parseDate?(input: string, format?: string): Partial<TPSComponents>;
+    parseDate(input: string, format?: string): Partial<TPSComponents>;
     /**
      * Format TPS components to a calendar-specific date string.
      * Inverse of parseDate().
@@ -136,7 +183,7 @@ export interface CalendarDriver {
      * driver.format({ year: 1447, month: 7, day: 21 }, 'short'); // → '21/7/1447'
      * ```
      */
-    format?(components: Partial<TPSComponents>, format?: string): string;
+    format(components: Partial<TPSComponents>, format?: string): string;
     /**
      * Validate a calendar-specific date string or components.
      *
@@ -149,7 +196,7 @@ export interface CalendarDriver {
      * driver.validate({ year: 1447, month: 7, day: 31 }); // → false (Rajab has 30 days)
      * ```
      */
-    validate?(input: string | Partial<TPSComponents>): boolean;
+    validate(input: string | Partial<TPSComponents>): boolean;
     /**
      * Get calendar metadata (month names, day names, etc.).
      * Useful for UI rendering.
@@ -160,7 +207,7 @@ export interface CalendarDriver {
      * // → ['Muharram', 'Safar', 'Rabi I', ...]
      * ```
      */
-    getMetadata?(): CalendarMetadata;
+    getMetadata(): CalendarMetadata;
 }
 /**
  * Metadata about a calendar system.
@@ -195,9 +242,18 @@ export declare class TPS {
      * @param code - The calendar code.
      * @returns The driver or undefined.
      */
-    static getDriver(code: CalendarCode): CalendarDriver | undefined;
+    static getDriver(code: string): CalendarDriver | undefined;
     private static readonly REGEX_URI;
     private static readonly REGEX_TIME;
+    /**
+     * SANITIZER: Normalises a raw TPS input string before validation.
+     *
+     * Pure string-based — no parsing into components, no regex beyond simple
+     * character checks, no re-serialisation via buildTimePart / toURI.
+     *
+     * Token ranks (descending): m(8) c(7) y(6) m(5) d(4) h(3) m(2) s(1) m(0)
+     */
+    static sanitizeTimeInput(input: string): string;
     static validate(input: string): boolean;
     static parse(input: string): TPSComponents | null;
     /**
@@ -210,10 +266,14 @@ export declare class TPS {
      * CONVERTER: Creates a TPS Time Object string from a JavaScript Date.
      * Supports plugin drivers for non-Gregorian calendars.
      * @param date - The JS Date object (defaults to Now).
-     * @param calendar - The target calendar driver (default 'greg').
-     * @returns Canonical string (e.g., "T:greg.m3.c1.y26...").
+     * @param calendar - The target calendar driver (default `"tps"`).
+     * @param opts - Optional parameters; for built-in calendars the only
+     *   supported key is `order` which may be `'ascending'` or `'descending'`.
+     * @returns Canonical string (e.g., "T:tps.m3.c1.y26...").
      */
-    static fromDate(date?: Date, calendar?: CalendarCode): string;
+    static fromDate(date?: Date, calendar?: string, opts?: {
+        order?: TimeOrder;
+    }): string;
     /**
      * CONVERTER: Converts a TPS string to a Date in a target calendar format.
      * Uses plugin drivers for cross-calendar conversion.
@@ -221,7 +281,7 @@ export declare class TPS {
      * @param targetCalendar - The target calendar code (e.g., 'hij').
      * @returns A TPS string in the target calendar, or null if invalid.
      */
-    static to(targetCalendar: CalendarCode, tpsString: string): string | null;
+    static to(targetCalendar: string, tpsString: string): string | null;
     /**
      * CONVERTER: Reconstructs a JavaScript Date object from a TPS string.
      * Supports plugin drivers for non-Gregorian calendars.
@@ -231,7 +291,7 @@ export declare class TPS {
     static toDate(tpsString: string): Date | null;
     /**
      * Parse a calendar-specific date string into TPS components.
-     * Requires the driver to implement the optional `parseDate` method.
+     * Requires the driver to implement `parseDate`.
      *
      * @param calendar - The calendar code (e.g., 'hij')
      * @param dateString - Date string in calendar-native format (e.g., '1447-07-21')
@@ -244,10 +304,10 @@ export declare class TPS {
      * // { calendar: 'hij', year: 1447, month: 7, day: 21 }
      *
      * const uri = TPS.toURI({ ...components, latitude: 31.95, longitude: 35.91 });
-     * // "tps://31.95,35.91@T:hij.y1447.M07.d21"
+     * // "tps://31.95,35.91@T:hij.y1447.m07.d21"
      * ```
      */
-    static parseCalendarDate(calendar: CalendarCode, dateString: string, format?: string): Partial<TPSComponents> | null;
+    static parseCalendarDate(calendar: string, dateString: string, format?: string): Partial<TPSComponents> | null;
     /**
      * Convert a calendar-specific date string directly to a TPS URI.
      * This is a convenience method that combines parseDate + toURI.
@@ -261,18 +321,18 @@ export declare class TPS {
      * ```ts
      * // With coordinates
      * TPS.fromCalendarDate('hij', '1447-07-21', { latitude: 31.95, longitude: 35.91 });
-     * // "tps://31.95,35.91@T:hij.y1447.M07.d21"
+     * // "tps://31.95,35.91@T:hij.y1447.m07.d21"
      *
      * // With privacy flag
      * TPS.fromCalendarDate('hij', '1447-07-21', { isHiddenLocation: true });
-     * // "tps://hidden@T:hij.y1447.M07.d21"
+     * // "tps://hidden@T:hij.y1447.m07.d21"
      *
      * // Without location
      * TPS.fromCalendarDate('hij', '1447-07-21');
-     * // "tps://unknown@T:hij.y1447.M07.d21"
+     * // "tps://unknown@T:hij.y1447.m07.d21"
      * ```
      */
-    static fromCalendarDate(calendar: CalendarCode, dateString: string, location?: {
+    static fromCalendarDate(calendar: string, dateString: string, location?: {
         latitude?: number;
         longitude?: number;
         altitude?: number;
@@ -282,7 +342,7 @@ export declare class TPS {
     }): string;
     /**
      * Format TPS components to a calendar-specific date string.
-     * Requires the driver to implement the optional `format` method.
+     * Requires the driver to implement `format`.
      *
      * @param calendar - The calendar code
      * @param components - TPS components to format
@@ -291,21 +351,61 @@ export declare class TPS {
      *
      * @example
      * ```ts
-     * const tps = TPS.parse('tps://unknown@T:hij.y1447.M07.d21');
+     * const tps = TPS.parse('tps://unknown@T:hij.y1447.m07.d21');
      * const formatted = TPS.formatCalendarDate('hij', tps);
      * // "1447-07-21"
      * ```
      */
-    static formatCalendarDate(calendar: CalendarCode, components: Partial<TPSComponents>, format?: string): string;
+    static formatCalendarDate(calendar: string, components: Partial<TPSComponents>, format?: string): string;
+    /**
+     * Generate the canonical `T:` time string for a set of components.  The
+     * `order` field (or `comp.order`) controls whether tokens are emitted in
+     * ascending or descending hierarchy; if undefined the default
+     * `'descending'` orientation is used.
+     *
+     * Drivers may ignore this helper and produce their own time strings if they
+     * implement custom ordering logic.
+     */
+    static buildTimePart(comp: TPSComponents): string;
+    /**
+     * Parse the *time* portion of a TPS string (optionally beginning with
+     * `T:`) into components and determine the component ordering.  This helper
+     * accepts tokens in **any** sequence and will return an `order` value of
+     * `'ascending'` or `'descending'`.
+     *
+     * The caller is responsible for stripping off a leading signature or other
+     * trailer characters; this method will drop anything after `!`, `;`, `?` or
+     * `#`.
+     *
+     * ### `m`-token disambiguation
+     * All four of millennium (rank 8), month (rank 5), minute (rank 2) and
+     * millisecond (rank 0) share the single-character prefix `m`.  They are told
+     * apart by their **position relative to the neighbouring tokens**.  The
+     * algorithm is:
+     *
+     * 1. Pre-scan the non-`m` tokens (c, y, d, h, s) whose ranks are fixed to
+     *    determine whether the string is ascending or descending.
+     * 2. While iterating, track `lastAssignedRank` – the rank of the most
+     *    recently processed token (m or non-m).
+     * 3. When an `m` token is encountered, derive its rank from `lastAssignedRank`
+     *    and the detected order:
+     *    - **DESC**  null → 8 (mill) | rank > 5 → 5 (month) | rank > 2 → 2 (min) | else → 0 (ms)
+     *    - **ASC**   null → 0 (ms)   | rank < 2 → 2 (min)   | rank < 5 → 5 (month) | else → 8 (mill)
+     *
+     * @param input - Time fragment (e.g. `"T:greg.m3.c1.y26"` or `"greg.m0.s25.m30"`)
+     */
+    static parseTimeString(input: string): {
+        components: Partial<TPSComponents>;
+        order: TimeOrder;
+    } | null;
     private static _mapGroupsToComponents;
-    private static pad;
 }
 /**
  * Decoded result from TPSUID7RB binary format.
  */
 export type TPSUID7RBDecodeResult = {
     /** Version identifier */
-    version: 'tpsuid7rb';
+    version: "tpsuid7rb";
     /** Epoch milliseconds (UTC) */
     epochMs: number;
     /** Whether the TPS payload was compressed */
@@ -344,7 +444,7 @@ export type TPSUID7RBEncodeOptions = {
  *
  * @example
  * ```ts
- * const tps = 'tps://31.95,35.91@T:greg.m3.c1.y26.M01.d09';
+ * const tps = 'tps://31.95,35.91@T:greg.m3.c1.y26.m01.d09';
  *
  * // Encode to binary
  * const bytes = TPSUID7RB.encodeBinary(tps);
@@ -418,6 +518,7 @@ export declare class TPSUID7RB {
         longitude?: number;
         altitude?: number;
         compress?: boolean;
+        order?: TimeOrder;
     }): string;
     /**
      * Generate a TPS string from a Date and optional location.
@@ -468,3 +569,61 @@ export declare class TPSUID7RB {
     /** Generate cryptographically secure random bytes */
     private static randomBytes;
 }
+/**
+ * `TpsDate` is a Date-like wrapper with native TPS conversion helpers.
+ *
+ * It mirrors common JavaScript `Date` construction patterns:
+ * - `new TpsDate()`
+ * - `new TpsDate(ms)`
+ * - `new TpsDate(isoString)`
+ * - `new TpsDate(tpsString)`
+ * - `new TpsDate(year, monthIndex, day?, hour?, minute?, second?, ms?)`
+ */
+export declare class TpsDate {
+    private readonly internal;
+    private getTpsComponents;
+    private getTpsFullYear;
+    constructor();
+    constructor(value: string | number | Date | TpsDate);
+    constructor(year: number, monthIndex: number, day?: number, hours?: number, minutes?: number, seconds?: number, ms?: number);
+    private static looksLikeTPS;
+    static now(): number;
+    static parse(input: string): number;
+    static UTC(year: number, monthIndex: number, day?: number, hours?: number, minutes?: number, seconds?: number, ms?: number): number;
+    static fromTPS(tps: string): TpsDate;
+    toGregorianDate(): Date;
+    toDate(): Date;
+    toTPS(calendar?: string, opts?: {
+        order?: TimeOrder;
+    }): string;
+    toTPSURI(calendar?: string, opts?: {
+        order?: TimeOrder;
+        latitude?: number;
+        longitude?: number;
+        altitude?: number;
+        isUnknownLocation?: boolean;
+        isHiddenLocation?: boolean;
+        isRedactedLocation?: boolean;
+    }): string;
+    getTime(): number;
+    valueOf(): number;
+    toString(): string;
+    toISOString(): string;
+    toUTCString(): string;
+    toJSON(): string | null;
+    getFullYear(): number;
+    getUTCFullYear(): number;
+    getMonth(): number;
+    getUTCMonth(): number;
+    getDate(): number;
+    getUTCDate(): number;
+    getHours(): number;
+    getUTCHours(): number;
+    getMinutes(): number;
+    getUTCMinutes(): number;
+    getSeconds(): number;
+    getUTCSeconds(): number;
+    getMilliseconds(): number;
+    getUTCMilliseconds(): number;
+    [Symbol.toPrimitive](hint: string): string | number;
+}