@finos/sail-env 0.0.0-stage → 3.0.0-beta.1

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# `@finos/sail-env`
 
-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.
+Tiny shared helpers so Sail host shells (`sail-finance`, `sail-one`, `sail-v2-web`, …) read the
+**same URL query params and Vite env keys** when they boot a Desktop Agent.
+
+This package does not talk to FDC3, open apps, or configure the conformance toolbox. It only
+parses strings and exports one constant.
+
+## Documentation
+
+[fdc3-sail.finos.org/docs/packages/sail-env/overview](https://fdc3-sail.finos.org/docs/packages/sail-env/overview)
+
+## What it exports
+
+| Export | Role |
+|--------|------|
+| `SAIL_MAX_FDC3_VERSION` | `"3.0"` — value hosts pass as advertised max wire version to `SailDesktopAgent` |
+| `resolveDeepLinkAppId(search)` | `?appId=` → open that directory app after start |
+| `resolveFdc3Directory(search)` | `?fdc3Directory=` → sole App Directory URL from the query |
+| `resolveNoSplash(search)` | `?noSplash=1` / `true` → hide splash / welcome chrome |
+| `resolveFdc3DirectoryUrl(raw)` | Non-empty check for `VITE_FDC3_DIRECTORY_URL` |
+| `isAutoResolve(raw)` | `VITE_AUTO_RESOLVE === "1"` → programmatic intent pick |
+| `resolveSoleFdc3Directory({ search, viteDirectoryUrl })` | Query `fdc3Directory` wins over Vite env |
+
+Vite host typings:
+
+```ts
+/// <reference types="@finos/sail-env/vite" />
+```
+
+Declares `import.meta.env.VITE_FDC3_DIRECTORY_URL` and `VITE_AUTO_RESOLVE`.
+
+## Typical host usage
+
+```ts
+import {
+  SAIL_MAX_FDC3_VERSION,
+  isAutoResolve,
+  resolveDeepLinkAppId,
+  resolveSoleFdc3Directory,
+} from "@finos/sail-env"
+
+const soleDirectoryUrl = resolveSoleFdc3Directory({
+  search: window.location.search,
+  viteDirectoryUrl: import.meta.env.VITE_FDC3_DIRECTORY_URL,
+})
+const autoResolve = isAutoResolve(import.meta.env.VITE_AUTO_RESOLVE)
+const deepLinkAppId = resolveDeepLinkAppId(window.location.search)
+
+// then: construct SailDesktopAgent with maxFdc3Version: SAIL_MAX_FDC3_VERSION,
+// optional sole directory, auto-resolve intent UI, and deep-link open
+```
+
+Example URL:
+
+```
+/?appId=Conformance1&fdc3Directory=https://example.com/apps.json&noSplash=1
+```
+
+## License
+
+Copyright 2025–2026 FINOS. Distributed under the Apache 2.0 License.

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared Sail host helpers: URL query params, Vite env strings, and the
+ * advertised max FDC3 wire version constant. No FDC3 protocol logic.
+ */
+/** Advertised maximum FDC3 API version Sail Desktop Agents support. */
+export declare const SAIL_MAX_FDC3_VERSION: "3.0";
+export type SailMaxFdc3Version = typeof SAIL_MAX_FDC3_VERSION;
+/**
+ * Deep-link app id from a query string (`?appId=…`).
+ */
+export declare function resolveDeepLinkAppId(search: string | URLSearchParams): string | undefined;
+/**
+ * Optional sole App Directory URL (`?fdc3Directory=https://…`).
+ * When set, hosts should use this directory only.
+ */
+export declare function resolveFdc3Directory(search: string | URLSearchParams): string | undefined;
+/**
+ * Suppress splash / welcome chrome when `?noSplash=1` or `true`.
+ */
+export declare function resolveNoSplash(search: string | URLSearchParams): boolean;
+/**
+ * Read `VITE_FDC3_DIRECTORY_URL` (or any raw string from the host).
+ */
+export declare function resolveFdc3DirectoryUrl(raw?: string | null): string | undefined;
+/**
+ * True when `VITE_AUTO_RESOLVE` / equivalent is `"1"` (programmatic intent pick).
+ */
+export declare function isAutoResolve(raw?: string | null): boolean;
+/**
+ * Effective sole App Directory: query `fdc3Directory` wins over Vite env.
+ */
+export declare function resolveSoleFdc3Directory(options?: {
+    search?: string | URLSearchParams;
+    viteDirectoryUrl?: string | null;
+}): string | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,EAAG,KAAc,CAAA;AAEnD,MAAM,MAAM,kBAAkB,GAAG,OAAO,qBAAqB,CAAA;AAM7D;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,MAAM,GAAG,SAAS,CAGzF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,MAAM,GAAG,SAAS,CAGzF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,OAAO,CAGzE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAE/E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE;IACjD,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe,CAAA;IACjC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACjC,GAAG,MAAM,GAAG,SAAS,CAGrB"}

package/dist/index.js

@@ -0,0 +1,50 @@
+/**
+ * Shared Sail host helpers: URL query params, Vite env strings, and the
+ * advertised max FDC3 wire version constant. No FDC3 protocol logic.
+ */
+/** Advertised maximum FDC3 API version Sail Desktop Agents support. */
+export const SAIL_MAX_FDC3_VERSION = "3.0";
+function toSearchParams(search) {
+    return typeof search === "string" ? new URLSearchParams(search) : search;
+}
+/**
+ * Deep-link app id from a query string (`?appId=…`).
+ */
+export function resolveDeepLinkAppId(search) {
+    const appId = toSearchParams(search).get("appId");
+    return appId && appId.length > 0 ? appId : undefined;
+}
+/**
+ * Optional sole App Directory URL (`?fdc3Directory=https://…`).
+ * When set, hosts should use this directory only.
+ */
+export function resolveFdc3Directory(search) {
+    const url = toSearchParams(search).get("fdc3Directory");
+    return url && url.length > 0 ? url : undefined;
+}
+/**
+ * Suppress splash / welcome chrome when `?noSplash=1` or `true`.
+ */
+export function resolveNoSplash(search) {
+    const raw = toSearchParams(search).get("noSplash");
+    return raw === "1" || raw === "true";
+}
+/**
+ * Read `VITE_FDC3_DIRECTORY_URL` (or any raw string from the host).
+ */
+export function resolveFdc3DirectoryUrl(raw) {
+    return raw && raw.length > 0 ? raw : undefined;
+}
+/**
+ * True when `VITE_AUTO_RESOLVE` / equivalent is `"1"` (programmatic intent pick).
+ */
+export function isAutoResolve(raw) {
+    return raw === "1";
+}
+/**
+ * Effective sole App Directory: query `fdc3Directory` wins over Vite env.
+ */
+export function resolveSoleFdc3Directory(options) {
+    const fromQuery = options?.search ? resolveFdc3Directory(options.search) : undefined;
+    return fromQuery ?? resolveFdc3DirectoryUrl(options?.viteDirectoryUrl);
+}

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/dist/index.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vite-plus/test";
+import { isAutoResolve, resolveDeepLinkAppId, resolveFdc3Directory, resolveNoSplash, resolveSoleFdc3Directory, } from "./index.js";
+describe("sail-env query helpers", () => {
+    it("resolves appId", () => {
+        expect(resolveDeepLinkAppId("?appId=Conformance1")).toBe("Conformance1");
+        expect(resolveDeepLinkAppId("?")).toBeUndefined();
+    });
+    it("resolves fdc3Directory", () => {
+        expect(resolveFdc3Directory("?fdc3Directory=https://example.com/apps.json")).toBe("https://example.com/apps.json");
+        expect(resolveFdc3Directory("?conformanceDirectory=https://x")).toBeUndefined();
+    });
+    it("resolves noSplash", () => {
+        expect(resolveNoSplash("?noSplash=1")).toBe(true);
+        expect(resolveNoSplash("?noSplash=true")).toBe(true);
+        expect(resolveNoSplash("?noSplash=0")).toBe(false);
+    });
+    it("prefers query directory over Vite env", () => {
+        expect(resolveSoleFdc3Directory({
+            search: "?fdc3Directory=https://query.example/a.json",
+            viteDirectoryUrl: "https://env.example/b.json",
+        })).toBe("https://query.example/a.json");
+        expect(resolveSoleFdc3Directory({
+            search: "?",
+            viteDirectoryUrl: "https://env.example/b.json",
+        })).toBe("https://env.example/b.json");
+    });
+    it("isAutoResolve", () => {
+        expect(isAutoResolve("1")).toBe(true);
+        expect(isAutoResolve("0")).toBe(false);
+    });
+});

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@finos/sail-env",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.0.0-beta.1",
+  "description": "Shared Sail host URL query and Vite env helpers (appId, fdc3Directory, auto-resolve, SAIL_MAX_FDC3_VERSION).",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/finos/FDC3-Sail",
+  "repository": "github:finos/FDC3-Sail",
+  "bugs": "https://github.com/finos/FDC3-Sail/issues",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./vite": "./vite.d.ts"
+  },
+  "files": [
+    "dist",
+    "vite.d.ts"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vp test run",
+    "lint": "vp lint ."
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  }
+}

package/vite.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared Vite `ImportMetaEnv` keys for Sail Desktop Agent hosts.
+ * Host packages: `/// <reference types="@finos/sail-env/vite" />`
+ */
+interface ImportMetaEnv {
+  /** Sole App Directory URL when set (CI / deep-link). */
+  readonly VITE_FDC3_DIRECTORY_URL?: string
+  /** `"1"` → programmatic intent resolution (no UI). */
+  readonly VITE_AUTO_RESOLVE?: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}