@nextera.one/tps-standard 0.4.3 → 0.5.1

package/LICENSE

@@ -0,0 +1,192 @@
+                                                        Apache License
+                                                Version 2.0, January 2004
+                                            http://www.apache.org/licenses/
+
+                TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+                1. Definitions.
+
+                    "License" shall mean the terms and conditions for use, reproduction,
+                    and distribution as defined by Sections 1 through 9 of this document.
+
+                    "Licensor" shall mean the copyright owner or entity authorized by
+                    the copyright owner that is granting the License.
+
+                    "Legal Entity" shall mean the union of the acting entity and all
+                    other entities that control, are controlled by, or are under common
+                    control with that entity. For the purposes of this definition,
+                    "control" means (i) the power, direct or indirect, to cause the
+                    direction or management of such entity, whether by contract or
+                    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+                    outstanding shares, or (iii) beneficial ownership of such entity.
+
+                    "You" (or "Your") shall mean an individual or Legal Entity
+                    exercising permissions granted by this License.
+
+                    "Source" form shall mean the preferred form for making modifications,
+                    including but not limited to software source code, documentation
+                    source, and configuration files.
+
+                    "Object" form shall mean any form resulting from mechanical
+                    transformation or translation of a Source form, including but
+                    not limited to compiled object code, generated documentation,
+                    and conversions to other media types.
+
+                    "Work" shall mean the work of authorship, whether in Source or
+                    Object form, made available under the License, as indicated by a
+                    copyright notice that is included in or attached to the work
+                    (an example is provided in the Appendix below).
+
+                    "Derivative Works" shall mean any work, whether in Source or Object
+                    form, that is based on (or derived from) the Work and for which the
+                    editorial revisions, annotations, elaborations, or other modifications
+                    represent, as a whole, an original work of authorship. For the purposes
+                    of this License, Derivative Works shall not include works that remain
+                    separable from, or merely link (or bind by name) to the interfaces of,
+                    the Work and Derivative Works thereof.
+
+                    "Contribution" shall mean any work of authorship, including
+                    the original version of the Work and any modifications or additions
+                    to that Work or Derivative Works thereof, that is intentionally
+                    submitted to Licensor for inclusion in the Work by the copyright owner
+                    or by an individual or Legal Entity authorized to submit on behalf of
+                    the copyright owner. For the purposes of this definition, "submitted"
+                    means any form of electronic, verbal, or written communication sent
+                    to the Licensor or its representatives, including but not limited to
+                    communication on electronic mailing lists, source code control systems,
+                    and issue tracking systems that are managed by, or on behalf of, the
+                    Licensor for the purpose of discussing and improving the Work, but
+                    excluding communication that is conspicuously marked or otherwise
+                    designated in writing by the copyright owner as "Not a Contribution."
+
+                    "Contributor" shall mean Licensor and any individual or Legal Entity
+                    on behalf of whom a Contribution has been received by Licensor and
+                    subsequently incorporated within the Work.
+
+                2. Grant of Copyright License. Subject to the terms and conditions of
+                    this License, each Contributor hereby grants to You a perpetual,
+                    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+                    copyright license to reproduce, prepare Derivative Works of,
+                    publicly display, publicly perform, sublicense, and distribute the
+                    Work and such Derivative Works in Source or Object form.
+
+                3. Grant of Patent License. Subject to the terms and conditions of
+                    this License, each Contributor hereby grants to You a perpetual,
+                    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+                    (except as stated in this section) patent license to make, have made,
+                    use, offer to sell, sell, import, and otherwise transfer the Work,
+                    where such license applies only to those patent claims licensable
+                    by such Contributor that are necessarily infringed by their
+                    Contribution(s) alone or by combination of their Contribution(s)
+                    with the Work to which such Contribution(s) was submitted. If You
+                    institute patent litigation against any entity (including a
+                    cross-claim or counterclaim in a lawsuit) alleging that the Work
+                    or a Contribution incorporated within the Work constitutes direct
+                    or contributory patent infringement, then any patent licenses
+                    granted to You under this License for that Work shall terminate
+                    as of the date such litigation is filed.
+
+                4. Redistribution. You may reproduce and distribute copies of the
+                    Work or Derivative Works thereof in any medium, with or without
+                    modifications, and in Source or Object form, provided that You
+                    meet the following conditions:
+
+                    (a) You must give any other recipients of the Work or
+                         Derivative Works a copy of this License; and
+
+                    (b) You must cause any modified files to carry prominent notices
+                         stating that You changed the files; and
+
+                    (c) You must retain, in the Source form of any Derivative Works
+                         that You distribute, all copyright, patent, trademark, and
+                         attribution notices from the Source form of the Work,
+                         excluding those notices that do not pertain to any part of
+                         the Derivative Works; and
+
+                    (d) If the Work includes a "NOTICE" text file as part of its
+                         distribution, then any Derivative Works that You distribute must
+                         include a readable copy of the attribution notices contained
+                         within such NOTICE file, excluding those notices that do not
+                         pertain to any part of the Derivative Works, in at least one
+                         of the following places: within a NOTICE text file distributed
+                         as part of the Derivative Works; within the Source form or
+                         documentation, if provided along with the Derivative Works; or,
+                         within a display generated by the Derivative Works, if and
+                         wherever such third-party notices normally appear. The contents
+                         of the NOTICE file are for informational purposes only and
+                         do not modify the License. You may add Your own attribution
+                         notices within Derivative Works that You distribute, alongside
+                         or as an addendum to the NOTICE text from the Work, provided
+                         that such additional attribution notices cannot be construed
+                         as modifying the License.
+
+                    You may add Your own copyright statement to Your modifications and
+                    may provide additional or different license terms and conditions
+                    for use, reproduction, or distribution of Your modifications, or
+                    for any such Derivative Works as a whole, provided Your use,
+                    reproduction, and distribution of the Work otherwise complies with
+                    the conditions stated in this License.
+
+                5. Submission of Contributions. Unless You explicitly state otherwise,
+                    any Contribution intentionally submitted for inclusion in the Work
+                    by You to the Licensor shall be under the terms and conditions of
+                    this License, without any additional terms or conditions.
+                    Notwithstanding the above, nothing herein shall supersede or modify
+                    the terms of any separate license agreement you may have executed
+                    with Licensor regarding such Contributions.
+
+                6. Trademarks. This License does not grant permission to use the trade
+                    names, trademarks, service marks, or product names of the Licensor,
+                    except as required for reasonable and customary use in describing the
+                    origin of the Work and reproducing the content of the NOTICE file.
+
+                7. Disclaimer of Warranty. Unless required by applicable law or
+                    agreed to in writing, Licensor provides the Work (and each
+                    Contributor provides its Contributions) on an "AS IS" BASIS,
+                    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+                    implied, including, without limitation, any warranties or conditions
+                    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+                    PARTICULAR PURPOSE. You are solely responsible for determining the
+                    appropriateness of using or redistributing the Work and assume any
+                    risks associated with Your exercise of permissions under this License.
+
+                8. Limitation of Liability. In no event and under no legal theory,
+                    whether in tort (including negligence), contract, or otherwise,
+                    unless required by applicable law (such as deliberate and grossly
+                    negligent acts) or agreed to in writing, shall any Contributor be
+                    liable to You for damages, including any direct, indirect, special,
+                    incidental, or consequential damages of any character arising as a
+                    result of this License or out of the use or inability to use the
+                    Work (including but not limited to damages for loss of goodwill,
+                    work stoppage, computer failure or malfunction, or any and all
+                    other commercial damages or losses), even if such Contributor
+                    has been advised of the possibility of such damages.
+
+                9. Accepting Warranty or Additional Liability. While redistributing
+                    the Work or Derivative Works thereof, You may choose to offer,
+                    and charge a fee for, acceptance of support, warranty, indemnity,
+                    or other liability obligations and/or rights consistent with this
+                    License. However, in accepting such obligations, You may act only
+                    on Your own behalf and on Your sole responsibility, not on behalf
+                    of any other Contributor, and only if You agree to indemnify,
+                    defend, and hold each Contributor harmless for any liability
+                    incurred by, or claims asserted against, such Contributor by reason
+                    of your accepting any such warranty or additional liability.
+
+                END OF TERMS AND CONDITIONS
+
+                APPENDIX: How to apply the Apache License to your work.
+
+                    Copyright 2026 TPS Standards Working Group
+
+                    Licensed under the Apache License, Version 2.0 (the "License");
+                    you may not use this file except in compliance with the License.
+                    You may obtain a copy of the License at
+
+                         http://www.apache.org/licenses/LICENSE-2.0
+
+                    Unless required by applicable law or agreed to in writing, software
+                    distributed under the License is distributed on an "AS IS" BASIS,
+                    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+                    See the License for the specific language governing permissions and
+                    limitations under the License.

package/README.md

@@ -1,5 +1,7 @@
 # TPS — Temporal Positioning Standard
 
+![TPS — Temporal Positioning Standard](assets/tps-banner.svg)
+
 > **A universal coordinate system for Space, Time, and Context.**
 
 TPS defines a deterministic way to represent **when** something happened, **where** it happened, and **under which calendar**, using a single, machine-readable identifier.
@@ -7,7 +9,7 @@ TPS defines a deterministic way to represent **when** something happened, **wher
 ## 📦 Installation
 
 ```bash
-npm install tps-standard
+npm i @nextera.one/tps-standard
 ```
 
 ## 🚀 Quick Start
@@ -15,27 +17,27 @@ npm install tps-standard
 ### Basic Example
 
 ```ts
-import { TPS } from 'tps-standard';
+import { TPS } from "@nextera.one/tps-standard";
 
 // Create a TPS time string from current date
-const nowTime = TPS.fromDate(new Date(), 'greg');
+const nowTime = TPS.fromDate(new Date(), "greg");
 console.log(nowTime);
 // Output: "T:greg.m3.c1.y26.M01.d07.h13.n20.s45"
 
 // Parse a full TPS URI with location and extensions
-const uri = 'tps://31.95,35.91,800@T:greg.m3.c1.y26.M01.d07.h13.n20;f4;r7';
+const uri = "tps://31.95,35.91,800m@T:greg.m3.c1.y26.M01.d07.h13.n20;f4.r7";
 const parsed = TPS.parse(uri);
 console.log(parsed);
 // { latitude: 31.95, longitude: 35.91, altitude: 800, calendar: 'greg', year: 26, ... }
 
 // Convert back to URI
 const components = {
-  calendar: 'greg',
+  calendar: "greg",
   year: 26,
   month: 1,
   day: 7,
   latitude: 31.95,
-  longitude: 35.91
+  longitude: 35.91,
 };
 const uriString = TPS.toURI(components);
 console.log(uriString);
@@ -52,34 +54,37 @@ TPS represents time as a coordinate using this hierarchy:
 T:greg.m3.c1.y26.M01.d07.h13.n20.s45
 ```
 
-| Component | Meaning |
-|-----------|---------|
-| `greg` | Calendar code (gregorian) |
-| `m3` | Millennium 3 (2000-2999) |
-| `c1` | Century 1 (2000-2099) |
-| `y26` | Year 26 (2026) |
-| `M01` | Month 01 (January) |
-| `d07` | Day 07 |
-| `h13` | Hour 13 (1:00 PM) |
-| `n20` | Minute 20 |
-| `s45` | Second 45 |
+| Component | Meaning                   |
+| --------- | ------------------------- |
+| `greg`    | Calendar code (gregorian) |
+| `m3`      | Millennium 3 (2000-2999)  |
+| `c1`      | Century 1 (2000-2099)     |
+| `y26`     | Year 26 (2026)            |
+| `M01`     | Month 01 (January)        |
+| `d07`     | Day 07                    |
+| `h13`     | Hour 13 (1:00 PM)         |
+| `n20`     | Minute 20                 |
+| `s45`     | Second 45                 |
 
 Partial coordinates represent **time volumes** (entire year, century, etc.).
 
 ### TPS URI Format
 
 **Canonical form:**
+
 ```
 tps://[SPACE]@[TIME][;EXTENSIONS]
 ```
 
 #### Components
 
-| Component | Description |
-|-----------|-------------|
-| `SPACE` | `lat,lon[,alt]m` (WGS84) or `unknown`/`hidden`/`redacted` |
-| `TIME` | TPS Time format (`T:calendar.hierarchy`) |
-| `EXTENSIONS` | Optional context (key-value pairs separated by dots) |
+| Component    | Description                                               |
+| ------------ | --------------------------------------------------------- |
+| `SPACE`      | `lat,lon[,alt]m` (WGS84) or `unknown`/`hidden`/`redacted` |
+| `TIME`       | TPS Time format (`T:calendar.hierarchy`)                  |
+| `EXTENSIONS` | Optional context after `;`, pairs separated by `.`        |
+
+Extensions are encoded as compact pairs with no `=` (e.g. `;f4.r7` means `{ f: "4", r: "7" }`).
 
 #### Location Privacy
 
@@ -92,57 +97,156 @@ tps://[SPACE]@[TIME][;EXTENSIONS]
 
 - `greg` — Gregorian calendar (default)
 - `unix` — Unix epoch seconds
-- `hij` — Hijri (Islamic) — *requires driver*
-- `jul` — Julian — *requires driver*
-- `holo` — Holocene — *requires driver*
+- `hij` — Hijri (Islamic) — _requires driver_
+- `jul` — Julian — _requires driver_
+- `holo` — Holocene — _requires driver_
 
 ## 🔌 Plugin Architecture
 
-TPS supports custom calendar drivers for non-Gregorian systems.
+TPS supports custom calendar drivers for non-Gregorian systems. Drivers can wrap external date libraries (like `moment-hijri`, `@js-joda/extra`, etc.).
 
 ### CalendarDriver Interface
 
 ```ts
 export interface CalendarDriver {
   readonly code: CalendarCode;
+  readonly name?: string; // Optional human-readable name
+
+  // Required methods
   fromGregorian(date: Date): Partial<TPSComponents>;
   toGregorian(components: Partial<TPSComponents>): Date;
   fromDate(date: Date): string;
+
+  // Optional enhanced methods
+  parseDate?(input: string, format?: string): Partial<TPSComponents>;
+  format?(components: Partial<TPSComponents>, format?: string): string;
+  validate?(input: string | Partial<TPSComponents>): boolean;
+  getMetadata?(): CalendarMetadata;
 }
 ```
 
 ### Register a Custom Driver
 
 ```ts
-import { TPS, CalendarDriver, TPSComponents } from 'tps-standard';
+import { TPS, CalendarDriver, TPSComponents } from "@nextera.one/tps-standard";
 
 class HijriDriver implements CalendarDriver {
-  readonly code = 'hij';
+  readonly code = "hij";
+  readonly name = "Hijri (Islamic)";
+
+  // Parse a Hijri date string like '1447-07-21'
+  parseDate(input: string): Partial<TPSComponents> {
+    const [year, month, day] = input.split("-").map(Number);
+    return { calendar: "hij", year, month, day };
+  }
+
+  // Format components to Hijri date string
+  format(comp: Partial<TPSComponents>): string {
+    return `${comp.year}-${String(comp.month).padStart(2, "0")}-${String(
+      comp.day
+    ).padStart(2, "0")}`;
+  }
 
   fromGregorian(date: Date): Partial<TPSComponents> {
-    // Convert Gregorian date to Hijri components
-    // ... conversion logic ...
-    return { year: 1445, month: 7, day: 15 };
+    // Use external library for accurate conversion
+    // Example with moment-hijri:
+    // const m = moment(date);
+    // return { year: m.iYear(), month: m.iMonth() + 1, day: m.iDate() };
+    return { year: 1447, month: 7, day: 21 };
   }
 
   toGregorian(components: Partial<TPSComponents>): Date {
-    // Convert Hijri components to Gregorian Date
-    // ... conversion logic ...
+    // Reverse conversion using external library
     return new Date();
   }
 
   fromDate(date: Date): string {
     const comp = this.fromGregorian(date);
-    return `T:hij.y${comp.year}.M${comp.month}.d${comp.day}`;
+    const pad = (n?: number) => String(n || 0).padStart(2, "0");
+    return `T:hij.y${comp.year}.M${pad(comp.month)}.d${pad(comp.day)}`;
   }
 }
 
 // Register the driver
 TPS.registerDriver(new HijriDriver());
+```
+
+### Using Calendar Drivers
 
-// Now use it
-const hijriTime = TPS.fromDate(new Date(), 'hij');
-console.log(hijriTime);
+```ts
+// Parse a Hijri date string directly
+const components = TPS.parseCalendarDate("hij", "1447-07-21");
+// { calendar: 'hij', year: 1447, month: 7, day: 21 }
+
+// Convert to TPS URI with location
+const uri = TPS.fromCalendarDate("hij", "1447-07-21", {
+  latitude: 31.95,
+  longitude: 35.91,
+});
+// "tps://31.95,35.91@T:hij.y1447.M07.d21"
+
+// Format TPS components back to calendar-native string
+const parsed = TPS.parse("tps://unknown@T:hij.y1447.M07.d21");
+const formatted = TPS.formatCalendarDate("hij", parsed);
+// "1447-07-21"
+
+// Using the driver directly
+const driver = TPS.getDriver("hij");
+if (driver?.parseDate) {
+  const comp = driver.parseDate("1447-07-21");
+  const gregDate = driver.toGregorian(comp);
+}
+```
+
+### Wrapping External Libraries
+
+Example with `moment-hijri`:
+
+```ts
+import moment from "moment-hijri";
+
+class MomentHijriDriver implements CalendarDriver {
+  readonly code = "hij";
+
+  parseDate(input: string, format = "iYYYY-iMM-iDD"): Partial<TPSComponents> {
+    const m = moment(input, format);
+    return {
+      calendar: "hij",
+      year: m.iYear(),
+      month: m.iMonth() + 1,
+      day: m.iDate(),
+      hour: m.hour(),
+      minute: m.minute(),
+      second: m.second(),
+    };
+  }
+
+  fromGregorian(date: Date): Partial<TPSComponents> {
+    const m = moment(date);
+    return {
+      calendar: "hij",
+      year: m.iYear(),
+      month: m.iMonth() + 1,
+      day: m.iDate(),
+      hour: m.hour(),
+      minute: m.minute(),
+      second: m.second(),
+    };
+  }
+
+  toGregorian(comp: Partial<TPSComponents>): Date {
+    const m = moment(`${comp.year}-${comp.month}-${comp.day}`, "iYYYY-iM-iD");
+    return m.toDate();
+  }
+
+  fromDate(date: Date): string {
+    const c = this.fromGregorian(date);
+    const p = (n?: number) => String(n || 0).padStart(2, "0");
+    return `T:hij.y${c.year}.M${p(c.month)}.d${p(c.day)}.h${p(c.hour)}.n${p(
+      c.minute
+    )}.s${p(c.second)}`;
+  }
+}
 ```
 
 ## 📚 API Reference
@@ -152,8 +256,8 @@ console.log(hijriTime);
 Validates whether a string is properly formatted TPS.
 
 ```ts
-TPS.validate('tps://31.95,35.91@T:greg.m3.c1.y26'); // true
-TPS.validate('invalid'); // false
+TPS.validate("tps://31.95,35.91@T:greg.m3.c1.y26"); // true
+TPS.validate("invalid"); // false
 ```
 
 ### `TPS.parse(input: string): TPSComponents | null`
@@ -161,7 +265,9 @@ TPS.validate('invalid'); // false
 Parses a TPS string into components. Returns `null` if invalid.
 
 ```ts
-const parsed = TPS.parse('tps://31.95,35.91,800@T:greg.m3.c1.y26.M01.d07.h13.n20;f4;r7');
+const parsed = TPS.parse(
+  "tps://31.95,35.91,800m@T:greg.m3.c1.y26.M01.d07.h13.n20;f4.r7"
+);
 // {
 //   latitude: 31.95,
 //   longitude: 35.91,
@@ -184,14 +290,14 @@ Converts a components object into a canonical TPS URI string.
 
 ```ts
 const components = {
-  calendar: 'greg',
+  calendar: "greg",
   year: 26,
   month: 1,
   day: 7,
   latitude: 31.95,
   longitude: 35.91,
   altitude: 800,
-  extensions: { f: "4", r: "7" }
+  extensions: { f: "4", r: "7" },
 };
 const uri = TPS.toURI(components);
 // "tps://31.95,35.91,800m@T:greg.y26.M01.d07;f4.r7"
@@ -202,10 +308,10 @@ const uri = TPS.toURI(components);
 Generates a TPS time string from a JavaScript Date. Supports registered drivers.
 
 ```ts
-const timeString = TPS.fromDate(new Date(), 'greg');
+const timeString = TPS.fromDate(new Date(), "greg");
 // "T:greg.m3.c1.y26.M01.d07.h13.n20.s45"
 
-const unixTime = TPS.fromDate(new Date(), 'unix');
+const unixTime = TPS.fromDate(new Date(), "unix");
 // "T:unix.s1704729645.123"
 ```
 
@@ -214,7 +320,7 @@ const unixTime = TPS.fromDate(new Date(), 'unix');
 Converts a TPS string back to a JavaScript Date object.
 
 ```ts
-const date = TPS.toDate('T:greg.m3.c1.y26.M01.d07.h13.n20.s45');
+const date = TPS.toDate("T:greg.m3.c1.y26.M01.d07.h13.n20.s45");
 console.log(date); // Date object for 2026-01-07 13:20:45 UTC
 ```
 
@@ -223,8 +329,8 @@ console.log(date); // Date object for 2026-01-07 13:20:45 UTC
 Converts a TPS string from one calendar to another using registered drivers.
 
 ```ts
-const gregTime = 'T:greg.m3.c1.y26.M01.d07';
-const hijriTime = TPS.to('hij', gregTime);
+const gregTime = "T:greg.m3.c1.y26.M01.d07";
+const hijriTime = TPS.to("hij", gregTime);
 // Requires registered Hijri driver
 ```
 
@@ -242,7 +348,7 @@ TPS.registerDriver(hijriDriver);
 Retrieves a registered calendar driver.
 
 ```ts
-const driver = TPS.getDriver('hij');
+const driver = TPS.getDriver("hij");
 if (driver) {
   const components = driver.fromGregorian(new Date());
 }
@@ -284,7 +390,124 @@ interface TPSComponents {
 ### `CalendarCode`
 
 ```ts
-type CalendarCode = 'greg' | 'hij' | 'jul' | 'holo' | 'unix';
+type CalendarCode = "greg" | "hij" | "jul" | "holo" | "unix";
+```
+
+## 🆔 TPS-UID — Temporal Positioning Identifier
+
+TPS-UID is a **time-first, reversible identifier** format that binds an event to a TPS coordinate. Unlike UUIDs which identify records, TPS-UID identifies **events in spacetime** and allows exact reconstruction of the original TPS string.
+
+### Why TPS-UID?
+
+| Feature           | UUID v4/v7       | TPS-UID         |
+| ----------------- | ---------------- | --------------- |
+| **Purpose**       | Identify objects | Identify events |
+| **Time**          | Optional/weak    | Mandatory       |
+| **Reversible**    | ❌ No            | ✅ Yes          |
+| **Time-sortable** | v7 only          | ✅ Always       |
+| **Audit-grade**   | ❌ No            | ✅ Yes          |
+
+### Binary Schema
+
+```
+MAGIC   4 bytes   "TPU7"
+VER     1 byte    0x01
+FLAGS   1 byte    bit0 = compression
+TIME    6 bytes   48-bit epoch ms
+NONCE   4 bytes   collision guard
+LEN     varint    payload length
+TPS     bytes     UTF-8 TPS string
+```
+
+### Quick Start
+
+```ts
+import { TPSUID7RB } from "@nextera.one/tps-standard";
+
+// Create TPS-UID from a TPS string
+const tps = "tps://31.95,35.91@T:greg.m3.c1.y26.M01.d09.h14.n30.s25";
+const id = TPSUID7RB.encodeBinaryB64(tps);
+// → "tpsuid7rb_VFBVNwEAAZujKmvo..."
+
+// Decode back to original TPS (exact reconstruction)
+const decoded = TPSUID7RB.decodeBinaryB64(id);
+console.log(decoded.tps); // exact original TPS
+console.log(decoded.epochMs); // 1767969025000
+
+// Generate from current time
+const generated = TPSUID7RB.generate({
+  latitude: 32.0,
+  longitude: 35.0,
+});
+```
+
+### API Reference
+
+#### `TPSUID7RB.encodeBinary(tps, opts?): Uint8Array`
+
+Encode TPS string to binary bytes (canonical form).
+
+```ts
+const bytes = TPSUID7RB.encodeBinary(tps, { compress: true });
+```
+
+#### `TPSUID7RB.decodeBinary(bytes): TPSUID7RBDecodeResult`
+
+Decode binary bytes back to original TPS.
+
+```ts
+const decoded = TPSUID7RB.decodeBinary(bytes);
+// { version: 'tpsuid7rb', epochMs, compressed, nonce, tps }
+```
+
+#### `TPSUID7RB.encodeBinaryB64(tps, opts?): string`
+
+Encode to base64url string with prefix (transport form).
+
+```ts
+const id = TPSUID7RB.encodeBinaryB64(tps, { compress: true });
+// "tpsuid7rb_..."
+```
+
+#### `TPSUID7RB.decodeBinaryB64(id): TPSUID7RBDecodeResult`
+
+Decode base64url string back to original TPS.
+
+```ts
+const decoded = TPSUID7RB.decodeBinaryB64(id);
+console.log(decoded.tps); // exact original
+```
+
+#### `TPSUID7RB.validateBinaryB64(id): boolean`
+
+Validate base64url encoded TPS-UID format.
+
+```ts
+TPSUID7RB.validateBinaryB64("tpsuid7rb_VFB..."); // true
+TPSUID7RB.validateBinaryB64("invalid"); // false
+```
+
+#### `TPSUID7RB.generate(opts?): string`
+
+Generate TPS-UID from current time.
+
+```ts
+const id = TPSUID7RB.generate({
+  latitude: 32.0,
+  longitude: 35.0,
+  compress: true,
+});
+```
+
+### Database Schema (Recommended)
+
+```sql
+CREATE TABLE events (
+  epoch_ms BIGINT NOT NULL,
+  tps_uid  VARBINARY(96) NOT NULL,
+  tps      TEXT NOT NULL,
+  PRIMARY KEY (epoch_ms, tps_uid)
+);
 ```
 
 ## 🎯 Use Cases
@@ -306,4 +529,4 @@ type CalendarCode = 'greg' | 'hij' | 'jul' | 'holo' | 'unix';
 
 ## 📄 License
 
-MIT © 2026 TPS Standards Working Group
+Apache-2.0 — see [LICENSE](LICENSE).