@geniee-inc/sfa-kit 1.16.0 → 1.18.0

package/GUIDE.md

@@ -21,7 +21,97 @@ import pkg from '@geniee-inc/sfa-kit/package.json';
 // pkg.version -> '1.14.0'
 ```
 
-Two additional subpaths are available: `@geniee-inc/sfa-kit/signing` exposes bundle-signing utilities (`computeContentHash`, `computeSignature`, `createManifest`, `createManifestFromDirectory`) for Node.js environments, and `./package.json` exposes the manifest. Internal modules cannot be imported directly.
+Three additional subpaths are available: `@geniee-inc/sfa-kit/signing` exposes bundle-manifest utilities, `@geniee-inc/sfa-kit/bundle` builds and signs a static bundle in one call (both Node.js-only), and `./package.json` exposes the manifest. Internal modules cannot be imported directly.
+
+### Static bundle manifest (custom-tab uploads)
+
+A page uploaded through GENIEE's SFA/CRM settings UI as a custom tab is a framework-free static bundle — `index.html` + `manifest.json` + `assets/` — not a Next.js app. Its `manifest.json` carries the three fields Keystone's `BundleSignatureVerifier` reads: `studio_version`, `content_hash`, `signature`.
+
+**The signing key lives only in Keystone, so a page build never computes the signature itself.** It hashes the bundle locally and asks Keystone to sign:
+
+```ts
+import {
+  readBundleFiles,
+  computeContentHash,
+} from '@geniee-inc/sfa-kit/signing';
+import type { BundleManifest } from '@geniee-inc/sfa-kit/signing';
+
+const files = await readBundleFiles('dist');
+const contentHash = computeContentHash(files);
+
+// Keystone holds the signing key, so ask it for the signature. The Bearer token
+// is the same one the rest of the API is called with.
+const response = await fetch(`${apiBase}/v1/pages/sign`, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${accessToken}`,
+  },
+  body: JSON.stringify({
+    studio_version: studioVersion,
+    content_hash: contentHash,
+  }),
+});
+if (!response.ok) throw new Error(`Signing failed: ${response.status}`);
+const { signature } = (await response.json()) as { signature: string };
+
+const manifest: BundleManifest = {
+  studio_version: studioVersion, // the Studio build version, NOT the sfa-kit npm version
+  content_hash: contentHash,
+  signature,
+};
+```
+
+### Building the bundle
+
+`@geniee-inc/sfa-kit/bundle` does the whole build in one call: it bundles the entry module with esbuild, writes `index.html`, hashes the result, gets the signature from Keystone and writes `manifest.json`.
+
+```ts
+import { buildStaticBundle } from '@geniee-inc/sfa-kit/bundle';
+
+await buildStaticBundle({
+  entry: 'entry.tsx', // renders <SfaLoginGate>…</SfaLoginGate> into #root
+  outDir: 'dist',
+  studioVersion: '0.5.0', // the Studio build version, NOT the sfa-kit npm version
+  apiBase: 'https://keystone-api-staging.chikyu.mobi',
+  accessToken: token,
+});
+```
+
+Or from the command line, which is the shorter path when a build script drives it:
+
+```bash
+SFA_KIT_ACCESS_TOKEN=<token> npx sfa-kit-bundle \
+  --entry entry.tsx \
+  --out dist \
+  --studio-version 0.5.0 \
+  --api-base https://keystone-api-staging.chikyu.mobi
+```
+
+The token comes from the environment rather than a flag, so it stays out of shell history and the process list.
+
+Then zip the **contents** of `dist/` — the bundle's files have to sit at the zip root, not inside a wrapper folder. Zipping is left to the caller: Node ships no zip writer, and every caller already has one.
+
+`esbuild` is an optional peer dependency; install it alongside the kit. Its options are fixed: JS, JSX, TS and CSS bundle, but there is no loader for images or fonts, so a page importing a `.png`, `.svg` or a font — including through `url()` in CSS — fails to build. Inline such assets as data URIs, or reference them by absolute URL.
+Nothing is written when signing fails, so a failed build never leaves an unsigned bundle behind to be uploaded by mistake.
+
+`studioVersion` has no default on purpose. The signature covers `"{studio_version}:{content_hash}"` and Keystone reads the field back separately, so a guessed value produces a valid signature over the wrong version.
+
+### Signing exports
+
+The lower-level pieces `buildStaticBundle` uses, for a caller that builds its own way:
+
+| Export                        | Needs the signing key |
+| ----------------------------- | --------------------- |
+| `readBundleFiles`             | No                    |
+| `computeContentHash`          | No                    |
+| `computeSignature`            | **Yes**               |
+| `createManifest`              | **Yes**               |
+| `createManifestFromDirectory` | **Yes**               |
+
+The three key-taking exports exist for the service that holds the key. Calling them from a page build means inventing a key, which Keystone will not accept — and the mistake is invisible at first, because bundle verification ships in `disabled` mode: the upload succeeds, and only starts failing once the mode is switched to `enforced`.
+
+`content_hash` must come from `computeContentHash`, never from hashing files back to back. The algorithm length-prefixes each path and each file's contents before feeding them into one running SHA-256; without those prefixes `"ab" + "c"` and `"a" + "bc"` hash identically, and the result never matches Keystone's own computation.
 
 ## Architecture
 
@@ -38,7 +128,7 @@ Every page uses `SfaLoginGate` as the outermost wrapper. It auto-detects the hos
 
 ### Props
 
-- **`apiBase`** (optional) — Overrides the auto-detected Keystone API endpoint. When omitted, the endpoint is resolved from a hostname: the embedding SFA/CRM host's when the page runs inside the iframe, the page's own when it runs standalone. Non-production environments (`stg.chikyu.mobi`, `dev01`-`dev09`, `devdc`, `deva0`, `dev-docker`, `dev.chikyu.local`, `localhost`, `127.0.0.1`, `[::1]`, and every Amplify host of the new frontend under `*.amplify.axiom.chikyu.mobi`: PR previews plus the `devNN.waf.` / `stg.waf.` record-detail hosts) use `https://keystone-api-staging.chikyu.mobi`; everything else (`app.chikyu.net`, any hostname not in that list) uses `https://keystone-api-production.chikyu.mobi`. Production is the fallback on purpose so a page that reaches a customer never silently talks to staging.
+- **`apiBase`** (optional) — Overrides the auto-detected Keystone API endpoint. When omitted, the endpoint is resolved from a hostname: the embedding SFA/CRM host's when the page runs inside the iframe, the page's own when it runs standalone. `dev09` (`dev09.chikyu.mobi` and `dev09.waf.amplify.axiom.chikyu.mobi`) has a Keystone of its own and uses `https://keystone-api-dev09.chikyu.mobi`. The other non-production environments (`stg.chikyu.mobi`, `dev01`-`dev08`, `devdc`, `deva0`, `dev-docker`, `dev.chikyu.local`, `localhost`, `127.0.0.1`, `[::1]`, and every Amplify host of the new frontend under `*.amplify.axiom.chikyu.mobi`: PR previews plus the `devNN.waf.` / `stg.waf.` record-detail hosts) use `https://keystone-api-staging.chikyu.mobi`; everything else (`app.chikyu.net`, any hostname not in that list) uses `https://keystone-api-production.chikyu.mobi`. Production is the fallback on purpose so a page that reaches a customer never silently talks to staging.
 - **`trustedOrigin`** (optional) — The origin of the SFA/CRM host page (e.g. `"https://app.chikyu.net"`). When provided and the page runs inside an iframe, `SfaLoginGate` uses the postMessage code-exchange flow (`POST /v1/auth/exchange`) instead of a login form. Injected automatically by Keystone's content endpoint at serve time.
 - **`defaultOrganizationId`** (optional) — The org ID to auto-select when the user's account belongs to multiple organizations. **Set this to the org that generated the page's metadata** (the org used in Step 0 schema discovery). Without this prop, multi-org accounts auto-select the first available org, which may not be the intended one. Use an env var, not a literal: `defaultOrganizationId={Number(process.env.NEXT_PUBLIC_DEFAULT_ORG_ID)}`.
 - **`objectKey`** (optional) — The object this page is built for (e.g. `"companies"`). The standalone DevToolbar shows it in the page-info tooltip and in the record ID placeholder. Pass it at **both** levels; omit it only if the page genuinely has no object.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geniee-inc/sfa-kit",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "React hooks and components for building pages that connect to GENIEE SFA/CRM data.",
   "type": "module",
   "main": "./src/index.js",
@@ -17,8 +17,19 @@
       "import": "./src/signing.js",
       "default": "./src/signing.js"
     },
+    "./bundle": {
+      "types": "./src/bundle.d.ts",
+      "import": "./src/bundle.js",
+      "default": "./src/bundle.js"
+    },
     "./package.json": "./package.json"
   },
+  "bin": {
+    "sfa-kit-bundle": "./src/bin/sfa-kit-bundle.js"
+  },
+  "engines": {
+    "node": ">=20.1.0"
+  },
   "sideEffects": false,
   "files": [
     "src",
@@ -33,9 +44,15 @@
   "license": "MIT",
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "esbuild": ">=0.18.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    }
   }
 }

package/src/bin/sfa-kit-bundle.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * @description Runs the bundler from the command line.
+ *
+ * Exported so the test suite drives the same entry point the `bin` does, and
+ * so a caller embedding it can pass argv explicitly.
+ *
+ * @returns The process exit code. 0 on success, 1 on any failure.
+ */
+export declare function runBundleCli(argv: readonly string[], env: Readonly<Record<string, string | undefined>>, out: {
+    log(message: string): void;
+    error(message: string): void;
+}): Promise<number>;

package/src/bin/sfa-kit-bundle.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { __awaiter } from "tslib";
+import { basename } from 'node:path';
+import { parseArgs } from 'node:util';
+import { buildStaticBundle } from '../lib/bundle/index.js';
+/** The access token is read from here, never from an argument. */
+const TOKEN_ENV = 'SFA_KIT_ACCESS_TOKEN';
+const USAGE = `sfa-kit-bundle — build and sign a static bundle for an SFA/CRM custom tab
+
+Usage:
+  ${TOKEN_ENV}=<token> npx sfa-kit-bundle \\
+    --entry entry.tsx \\
+    --out dist \\
+    --studio-version 0.5.0 \\
+    --api-base https://keystone-api-staging.chikyu.mobi
+
+Options:
+  --entry           Entry module that mounts the page into #root. Required.
+  --out             Output directory. Required.
+  --studio-version  The Studio build version this bundle targets, not the
+                    sfa-kit npm version. Required.
+  --api-base        Keystone API base, without a trailing slash. Required.
+  --title           <title> of the generated index.html. Default: SFA/CRM.
+  --help            Show this message.
+
+Environment:
+  ${TOKEN_ENV}  Bearer token for Keystone, the same one the rest of the
+  API is called with. Required, and read from the environment rather than an
+  argument so it does not land in shell history or in the process list.
+
+Writes index.html, assets/bundle.js and a signed manifest.json. Zip the
+contents of the output directory — the files have to sit at the zip root.
+Needs esbuild installed alongside the kit.`;
+const OPTIONS = {
+    entry: { type: 'string' },
+    out: { type: 'string' },
+    'studio-version': { type: 'string' },
+    'api-base': { type: 'string' },
+    title: { type: 'string' },
+    help: { type: 'boolean' },
+};
+/**
+ * @description Reads the flags, reporting a malformed command line as data.
+ *
+ * NOTE: `parseArgs` throws on a misspelled flag, a flag with no value, and a
+ * stray positional. Left to propagate, those would reject the promise the bin
+ * only attaches `.then()` to, and the user would get a stack trace where the
+ * usage text belongs.
+ */
+function parseCliOptions(argv) {
+    try {
+        const { values } = parseArgs({
+            args: [...argv],
+            options: OPTIONS,
+            allowPositionals: false,
+        });
+        return { values };
+    }
+    catch (thrown) {
+        return { error: thrown instanceof Error ? thrown.message : String(thrown) };
+    }
+}
+/**
+ * @description Runs the bundler from the command line.
+ *
+ * Exported so the test suite drives the same entry point the `bin` does, and
+ * so a caller embedding it can pass argv explicitly.
+ *
+ * @returns The process exit code. 0 on success, 1 on any failure.
+ */
+export function runBundleCli(argv, env, out) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f;
+        const parsed = parseCliOptions(argv);
+        if (parsed.error != null) {
+            out.error(`${parsed.error}\n\n${USAGE}`);
+            return 1;
+        }
+        const values = parsed.values;
+        if (values.help) {
+            out.log(USAGE);
+            return 0;
+        }
+        const missing = ['entry', 'out', 'studio-version', 'api-base']
+            .filter(name => { var _a; return ((_a = values[name]) !== null && _a !== void 0 ? _a : '') === ''; })
+            .map(name => `--${name}`);
+        const accessToken = (_a = env[TOKEN_ENV]) !== null && _a !== void 0 ? _a : '';
+        if (accessToken === '')
+            missing.push(TOKEN_ENV);
+        if (missing.length > 0) {
+            out.error(`Missing required: ${missing.join(', ')}\n\n${USAGE}`);
+            return 1;
+        }
+        try {
+            const manifest = yield buildStaticBundle(Object.assign({ entry: (_b = values.entry) !== null && _b !== void 0 ? _b : '', outDir: (_c = values.out) !== null && _c !== void 0 ? _c : '', studioVersion: (_d = values['studio-version']) !== null && _d !== void 0 ? _d : '', apiBase: (_e = values['api-base']) !== null && _e !== void 0 ? _e : '', accessToken }, (((_f = values.title) !== null && _f !== void 0 ? _f : '') === '' ? {} : { title: values.title })));
+            out.log(`Built and signed ${values.out} ` +
+                `(studio_version ${manifest.studio_version}, ` +
+                `content_hash ${manifest.content_hash}).`);
+            return 0;
+        }
+        catch (thrown) {
+            // NOTE: buildStaticBundle removes what it wrote, so there is normally
+            // nothing left to upload. The one case where output survives — cleanup
+            // itself failing — says so in its own message.
+            out.error(`${thrown instanceof Error ? thrown.message : String(thrown)}\n` +
+                'Nothing was signed, so nothing is ready to upload.');
+            return 1;
+        }
+    });
+}
+/** True when this module is what node was asked to run, not an import of it. */
+function isEntryPoint() {
+    // NOTE: the file name, not a substring of the path. `includes()` would also
+    // fire for a consumer script under, say, ~/work/sfa-kit-bundle-demo/, which
+    // would start the CLI merely because that script imported runBundleCli.
+    //
+    // `import.meta.url` would be the exact comparison, but Jest transforms this
+    // file to CommonJS, where that syntax does not parse and the whole suite
+    // fails to load.
+    const invoked = process.argv[1];
+    if (invoked == null)
+        return false;
+    const name = basename(invoked);
+    return name === 'sfa-kit-bundle' || name === 'sfa-kit-bundle.js';
+}
+/* istanbul ignore next -- the process wiring is exercised by running the bin */
+if (isEntryPoint()) {
+    // NOTE: no top-level await — the package's module target does not allow it.
+    void runBundleCli(process.argv.slice(2), process.env, {
+        log: message => console.log(message),
+        error: message => console.error(message),
+    })
+        .then(code => {
+        process.exitCode = code;
+    })
+        .catch((thrown) => {
+        // Nothing above should reject, but an unhandled rejection would exit 0
+        // on some Node versions — reporting a failed build as a success.
+        console.error(thrown instanceof Error ? thrown.message : String(thrown));
+        process.exitCode = 1;
+    });
+}

package/src/bundle.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Static bundle builder for GENIEE SFA/CRM custom-tab uploads.
+ *
+ * This subpath export (`@geniee-inc/sfa-kit/bundle`) is Node.js-only and needs
+ * `esbuild` installed alongside the kit. It produces the framework-free
+ * `index.html` + `assets/bundle.js` + signed `manifest.json` a page is uploaded
+ * as; the caller zips the result.
+ *
+ * @example
+ * ```ts
+ * import { buildStaticBundle } from '@geniee-inc/sfa-kit/bundle';
+ *
+ * await buildStaticBundle({
+ *   entry: 'entry.tsx',
+ *   outDir: 'dist',
+ *   studioVersion: '0.5.0',
+ *   apiBase: 'https://keystone-api-staging.chikyu.mobi',
+ *   accessToken: token,
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export type { BundleManifest } from './lib/signing/index.js';
+export type { BuildStaticBundleOptions } from './lib/bundle/index.js';
+export { buildStaticBundle } from './lib/bundle/index.js';

package/src/bundle.js

@@ -0,0 +1 @@
+export { buildStaticBundle } from './lib/bundle/index.js';

package/src/index.d.ts

@@ -34,7 +34,7 @@ export { ErrorBoundary } from './lib/components/ErrorBoundary';
 export { EmptyState } from './lib/components/EmptyState';
 export { FetchErrorState } from './lib/components/FetchErrorState';
 export { ErrorSnackbar } from './lib/components/ErrorSnackbar';
-export type { SfaAuth, SfaApiMode, SfaClientConfig, SfaRecord, SfaListResponse, SfaListParams, SfaFieldValue, SfaFieldKind, SfaFieldValueMapping, FieldGroupSpec, FieldGroupLayout, SfaFieldDescriptor, SfaFieldOption, SfaRelationDescriptor, SfaObjectDetail, SfaObjectSummary, SfaObjectCatalog, SfaObjectPermissions, SfaObjectOrigin, SfaRelationshipKind, SfaCardinality, SfaDescribeResult, SfaFieldTypeDescriptor, SfaFieldTypeCatalog, SfaFilterOperator, SfaCreateOptions, SfaFieldError, SfaBulkRowStatus, SfaBulkRowResult, SfaBulkRowError, SfaBulkUpdateRow, SfaBulkDeleteRow, } from './lib/provider/types';
+export type { SfaAuth, SfaApiMode, SfaAuthErrorHandler, SfaClientConfig, SfaRecord, SfaListResponse, SfaListParams, SfaFieldValue, SfaFieldKind, SfaFieldValueMapping, FieldGroupSpec, FieldGroupLayout, SfaFieldDescriptor, SfaFieldOption, SfaRelationDescriptor, SfaObjectDetail, SfaObjectSummary, SfaObjectCatalog, SfaObjectPermissions, SfaObjectOrigin, SfaRelationshipKind, SfaCardinality, SfaDescribeResult, SfaFieldTypeDescriptor, SfaFieldTypeCatalog, SfaFilterOperator, SfaCreateOptions, SfaFieldError, SfaBulkRowStatus, SfaBulkRowResult, SfaBulkRowError, SfaBulkUpdateRow, SfaBulkDeleteRow, } from './lib/provider/types';
 export { SFA_BULK_MAX_ROWS } from './lib/provider/SfaClient';
 export type { SfaSession, AuthResult, OrganizationChoice, } from './lib/auth/types';
 export { buildRecordDetailUrl, resolveHostOrigin, } from './lib/navigation/record-detail-url';

package/src/lib/auth/resolve-api-base.d.ts

@@ -1,12 +1,14 @@
 export declare const KEYSTONE_PRODUCTION_API_BASE = "https://keystone-api-production.chikyu.mobi";
 export declare const KEYSTONE_STAGING_API_BASE = "https://keystone-api-staging.chikyu.mobi";
+export declare const KEYSTONE_DEV09_API_BASE = "https://keystone-api-dev09.chikyu.mobi";
 /**
  * @description Resolves the Keystone API base URL from an origin.
  *
- * Every non-production chikyu environment — `stg.chikyu.mobi`, the dev tier,
- * local development, and Amplify PR previews — uses the staging Keystone API.
- * Everything else — `app.chikyu.net`, an origin this table does not know, or
- * no origin at all — uses production.
+ * `dev09` has a keystone of its own. Every other non-production chikyu
+ * environment — `stg.chikyu.mobi`, the rest of the dev tier, local development,
+ * and Amplify PR previews — uses the staging Keystone API. Everything else —
+ * `app.chikyu.net`, an origin this table does not know, or no origin at all —
+ * uses production.
  *
  * Production is the fallback on purpose: a page that reaches a real customer
  * must never silently talk to staging. A developer on an unrecognised host

package/src/lib/auth/resolve-api-base.js

@@ -1,6 +1,10 @@
 export const KEYSTONE_PRODUCTION_API_BASE = 'https://keystone-api-production.chikyu.mobi';
 export const KEYSTONE_STAGING_API_BASE = 'https://keystone-api-staging.chikyu.mobi';
-/** Dev-tier chikyu (legacy frontend) hosts: dev01-dev09, devdc, deva0, and the like. */
+export const KEYSTONE_DEV09_API_BASE = 'https://keystone-api-dev09.chikyu.mobi';
+/**
+ * Dev-tier chikyu (legacy frontend) hosts: dev01-dev08, devdc, deva0, and the
+ * like. `dev09` matches this too but is taken by `DEV09_HOSTNAMES` first.
+ */
 const DEV_HOST_PATTERN = /^dev\w+\.chikyu\.mobi$/;
 /**
  * Amplify-hosted new frontend. Covers PR previews
@@ -21,13 +25,26 @@ const LOCAL_HOSTNAMES = new Set([
 ]);
 /** Shared pre-production chikyu environments. */
 const STAGING_HOSTNAMES = new Set(['stg.chikyu.mobi']);
+/**
+ * dev09 has a keystone of its own. One keystone delegates to exactly one chikyu
+ * environment, so the staging keystone follows `stg` and this one follows
+ * `dev09`, the JapanAI Studio integration environment. Both of dev09's frontends
+ * are listed: the legacy chikyu host and the Amplify host that frames the page.
+ * Exact hostnames, because `DEV_HOST_PATTERN` and `AMPLIFY_PATTERN` below would
+ * otherwise claim them for staging.
+ */
+const DEV09_HOSTNAMES = new Set([
+    'dev09.chikyu.mobi',
+    'dev09.waf.amplify.axiom.chikyu.mobi',
+]);
 /**
  * @description Resolves the Keystone API base URL from an origin.
  *
- * Every non-production chikyu environment — `stg.chikyu.mobi`, the dev tier,
- * local development, and Amplify PR previews — uses the staging Keystone API.
- * Everything else — `app.chikyu.net`, an origin this table does not know, or
- * no origin at all — uses production.
+ * `dev09` has a keystone of its own. Every other non-production chikyu
+ * environment — `stg.chikyu.mobi`, the rest of the dev tier, local development,
+ * and Amplify PR previews — uses the staging Keystone API. Everything else —
+ * `app.chikyu.net`, an origin this table does not know, or no origin at all —
+ * uses production.
  *
  * Production is the fallback on purpose: a page that reaches a real customer
  * must never silently talk to staging. A developer on an unrecognised host
@@ -41,6 +58,8 @@ export function resolveApiBase(origin) {
     const hostname = hostnameOf(origin);
     if (hostname == null)
         return KEYSTONE_PRODUCTION_API_BASE;
+    if (DEV09_HOSTNAMES.has(hostname))
+        return KEYSTONE_DEV09_API_BASE;
     const isNonProduction = STAGING_HOSTNAMES.has(hostname) ||
         LOCAL_HOSTNAMES.has(hostname) ||
         DEV_HOST_PATTERN.test(hostname) ||

package/src/lib/auth/useEmbedSession.d.ts

@@ -1,3 +1,4 @@
+import type { SfaAuthErrorHandler } from '../provider/types';
 import type { EmbedContext } from './embed-protocol';
 import type { SfaSession } from './types';
 export type EmbedPhase = {
@@ -28,7 +29,7 @@ export type EmbedPhase = {
 export interface EmbedSessionState {
     readonly phase: EmbedPhase;
     /** Passed to SfaProvider so a 401 triggers the code-request fallback. */
-    readonly handleAuthError: () => void;
+    readonly handleAuthError: SfaAuthErrorHandler;
 }
 /**
  * @description Keeps an embedded page authenticated over the postMessage