@incode-sdks/incode-integrate 0.2.0 → 0.4.0

package/README.md

@@ -16,11 +16,19 @@ Apply the plan explicitly:
 npx @incode-sdks/incode-integrate --apply
 ```
 
-Scripted example:
+## Interactive Setup
 
-```sh
-npx @incode-sdks/incode-integrate --version 9.14.0 --api-url demo --backend-sessions yes --sdk-config manual --idv standard-nfc --flow-handling step-by-step --apply
-```
+In an interactive terminal, the CLI asks for:
+
+- Incode customer GitHub token
+- React Native NPM token
+- API URL: Demo, Production, or custom
+- API key, if the client is embedding the key
+- whether sessions are initiated on the backend, which enables the recommended no-api-key client approach
+- SDK configuration mode: online dashboard flow or manual in-code flow
+- manual IDV preset: Standard, Standard + NFC, or Standard + Session Recording
+- flow handling: end-to-end or step-by-step
+- iOS podspec source
 
 ## What It Updates
 
@@ -30,4 +38,73 @@ npx @incode-sdks/incode-integrate --version 9.14.0 --api-url demo --backend-sess
 - generated Incode flow files under `src/`
 - ignored local files such as `.env.local` and `.npmrc` when credentials are provided
 
-Secrets are not written to generated TypeScript, Gradle, Podfile, or README files.
+Secrets are not written to Gradle, Podfile, README, or committed generated TypeScript files.
+
+When `--apply` receives tokens, it writes them only to ignored local files:
+
+- `.env.local`: shell exports for `GITHUB_USERNAME`, `GITHUB_TOKEN`, `INCODE_API_URL`, optional `INCODE_API_KEY`, and optional `INCODE_SESSION_TOKEN`
+- `.npmrc`: npm registry auth for the React Native SDK package
+- `src/incodeRuntimeConfig.local.ts`: demo-app credential prefill generated from `.env.local`
+
+React Native does not automatically load `.env.local` at runtime. The generated local runtime config lets the demo app prefill the API key or backend session token from ignored local values.
+
+## Backend Sessions
+
+Use backend sessions for the recommended no-api-key client approach:
+
+```sh
+npx @incode-sdks/incode-integrate --backend-sessions yes --apply
+```
+
+In backend-session mode, the generated `src/IncodeExample.ts` appends `/0/` to the SDK `apiConfig.url`, for example `https://demo-api.incodesmile.com/0/`.
+
+The client app should pass the backend-created `session_token` as `sessionToken`; the helper maps it to the React Native SDK's `sessionConfig.token`.
+
+## Online Dashboard Flows
+
+When `--sdk-config online` is used, the generated helper puts the dashboard flow ID into `SESSION_CONFIG.configurationId` and starts onboarding with `IncodeSdk.startFlow({ sessionConfig })`.
+
+Manual mode uses generated `flowConfig` modules with `IncodeSdk.startOnboarding(...)` or `startOnboardingSection(...)`.
+
+## Scripted Examples
+
+```sh
+npx @incode-sdks/incode-integrate --version 9.14.0 --pod-source https --api-url demo --backend-sessions yes --sdk-config manual --idv standard-nfc --flow-handling step-by-step
+npx @incode-sdks/incode-integrate --version 9.14.0 --api-url production --backend-sessions no --sdk-config manual --idv standard-recording --flow-handling end-to-end --apply
+npx @incode-sdks/incode-integrate --sdk-config online --api-url demo --dashboard-url "https://dashboard.incodesmile.com/flows/example" --configuration-id "example-config-id"
+npx @incode-sdks/incode-integrate --yes
+```
+
+## Important Flags
+
+- `--apply`: update files; without this flag the CLI only prints a dry-run plan
+- `--yes`: use non-interactive defaults
+- `--version`: SDK version, for example `9.14.0`
+- `--pod-source`: `ssh` or `https`
+- `--api-url`: `demo`, `production`, or a custom URL
+- `--backend-sessions`: `yes` for the no-api-key client approach, `no` to use a client API key at runtime
+- `--api-key`: API key for client API-key mode
+- `--github-username`: GitHub username for Incode package access
+- `--github-token`: Incode customer GitHub token for package access
+- `--npm-token`: NPM token for React Native SDK package access
+- `--sdk-config`: `online` or `manual`
+- `--dashboard-url`: dashboard flow URL for online SDK configuration
+- `--configuration-id`: online configuration ID when known
+- `--idv`: `standard`, `standard-nfc`, or `standard-recording`
+- `--flow-handling`: `end-to-end` or `step-by-step`
+- `--test-mode`: default the sample app to SDK test mode
+- `--no-test-mode`: default the sample app to real-device mode
+
+## IDV Presets
+
+- `standard`: `IdScan`, `SelfieScan`, `FaceMatch`
+- `standard-nfc`: `IdScan`, `NFCScan`, `SelfieScan`, `FaceMatch`
+- `standard-recording`: `IdScan`, `SelfieScan`, `FaceMatch`, record-session config, and the Android video streaming dependency
+
+SDK package variant is derived from `--idv`:
+
+- `standard` installs the standard SDK package
+- `standard-nfc` installs the `nfc` SDK package variant
+- `standard-recording` installs the `streaming` / `vc` SDK package variant
+
+The CLI always writes the React Native SDK dependency as an npm registry version in `package.json`; it does not use local tarballs.

package/agent.js

@@ -164,6 +164,10 @@ function normalizeVersion(version) {
   return trimmed || DEFAULT_SDK_VERSION;
 }
 
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function normalizeVariant(variant) {
   const normalized = String(variant || "").trim().toLowerCase();
   const aliases = {
@@ -457,6 +461,20 @@ function parseStringConstant(content, name) {
   return double?.[1] || "";
 }
 
+function parseObjectStringProperty(content, name) {
+  const quoted = content.match(
+    new RegExp(`["']${escapeRegExp(name)}["']\\s*:\\s*["']([^"']*)["']`),
+  );
+  if (quoted) {
+    return quoted[1];
+  }
+
+  const unquoted = content.match(
+    new RegExp(`\\b${escapeRegExp(name)}\\b\\s*:\\s*["']([^"']*)["']`),
+  );
+  return unquoted?.[1] || "";
+}
+
 function parseBooleanConstant(content, name, fallback) {
   const match = content.match(new RegExp(`export const ${name}(?::[^=]+)? = (true|false)`));
   return match ? match[1] === "true" : fallback;
@@ -480,10 +498,14 @@ function extractConfigurationId(dashboardUrl) {
     }
 
     const fromPath = url.pathname.match(/(?:configuration|configurations|flow|flows)\/([^/?#]+)/i);
-    return fromPath?.[1] || "";
+    if (fromPath) {
+      return fromPath[1];
+    }
   } catch {
-    return "";
+    // Fall through and allow a raw flow/configuration ID.
   }
+
+  return /^[A-Za-z0-9_-]+$/.test(value) ? value : "";
 }
 
 function inferVariantFromDashboardUrl(dashboardUrl) {
@@ -613,6 +635,9 @@ function inferProductOptions(context) {
   const sdkConfigMode = normalizeConfigMode(parseStringConstant(incodeFlow, "SDK_CONFIGURATION_MODE"), "manual");
   const flowHandling = normalizeFlowHandling(parseStringConstant(incodeFlow, "FLOW_HANDLING"), "end-to-end");
   const dashboardUrl = parseStringConstant(incodeFlow, "DASHBOARD_FLOW_URL");
+  const configurationId =
+    parseObjectStringProperty(incodeFlow, "configurationId") ||
+    extractConfigurationId(dashboardUrl);
   const apiUrl = normalizeApiUrl(
     localSecrets.INCODE_API_URL || parseStringConstant(incodeRuntimeConfig, "INCODE_DEFAULT_API_URL"),
     API_URLS.demo.url,
@@ -634,7 +659,7 @@ function inferProductOptions(context) {
     apiKeyProvided: Boolean(localSecrets.INCODE_API_KEY),
     apiUrl,
     backendSessions: localBackendSessions,
-    configurationId: extractConfigurationId(dashboardUrl),
+    configurationId,
     dashboardUrl,
     dynamicLocalization: androidAppBuildGradle.includes("com.incode.sdk:extensions"),
     flowHandling,
@@ -651,6 +676,7 @@ function inferProductOptions(context) {
     sdkConfigMode,
     sdkVariant: currentDependency.variant,
     sdkVersion: currentDependency.version,
+    sessionToken: localSecrets.INCODE_SESSION_TOKEN || "",
     testMode,
     videoStreaming: androidAppBuildGradle.includes("com.incode.sdk:video-streaming"),
   };
@@ -766,6 +792,7 @@ async function promptForProductOptions(context, options) {
       sdkConfigMode,
       sdkVariant: variantForIdv(idv),
       sdkVersion,
+      sessionToken: current.sessionToken,
       videoStreaming: Boolean(IDV_PRESETS[idv].videoStreaming),
     };
   } finally {
@@ -836,6 +863,7 @@ function chooseProductOptions(context, options) {
     sdkConfigMode,
     sdkVariant: variantForIdv(idv),
     sdkVersion: normalizeVersion(options.version || DEFAULT_SDK_VERSION),
+    sessionToken: current.sessionToken,
     testMode: options.testMode === undefined ? current.testMode : options.testMode,
     videoStreaming:
       options.videoStreaming === undefined
@@ -882,8 +910,6 @@ export type FlowHandling = 'end-to-end' | 'step-by-step';
 
 export const SDK_CONFIGURATION_MODE: SdkConfigurationMode = '${productOptions.sdkConfigMode}';
 
-export const DASHBOARD_FLOW_URL = '${productOptions.dashboardUrl || ""}';
-
 export const IDV_PRESET = '${productOptions.idv}' as const;
 
 export const FLOW_HANDLING: FlowHandling = '${productOptions.flowHandling}';
@@ -925,6 +951,17 @@ export const INCODE_DEFAULT_TEST_MODE = ${productOptions.testMode};
 `;
 }
 
+function createLocalRuntimeConfigFile(productOptions) {
+  const credential = productOptions.backendSessions
+    ? productOptions.sessionToken
+    : productOptions.apiKey;
+
+  return `// Generated from ignored local env values for the demo app.
+// Do not commit real credentials in this file.
+export const INCODE_DEFAULT_CREDENTIAL = ${toTs(credential || "")};
+`;
+}
+
 function createLocalCredentialEnvFile(productOptions) {
   const lines = [
     "# Local Incode SDK credentials and runtime values. This file is ignored by git.",
@@ -950,7 +987,11 @@ function createLocalCredentialEnvFile(productOptions) {
   }
 
   if (productOptions.backendSessions) {
-    lines.push('export INCODE_SESSION_TOKEN="${INCODE_SESSION_TOKEN:-<token-from-your-backend>}"');
+    if (productOptions.sessionToken) {
+      lines.push(`export INCODE_SESSION_TOKEN="${escapeEnvValue(productOptions.sessionToken)}"`);
+    } else {
+      lines.push('export INCODE_SESSION_TOKEN="${INCODE_SESSION_TOKEN:-<token-from-your-backend>}"');
+    }
   }
 
   return `${lines.join("\n")}\n`;
@@ -969,6 +1010,7 @@ import {
   FLOW_CONFIG,
   FLOW_HANDLING,
   FLOW_RECORD_SESSION_CONFIG,
+  SDK_CONFIGURATION_MODE,
   SECTION_FLOW_CONFIGS,
   SESSION_CONFIG,
 } from './incodeFlow';
@@ -1020,6 +1062,10 @@ export async function startConfiguredOnboarding(options: StartIncodeOptions) {
 
   const sessionConfig = buildSessionConfig(options);
 
+  if (SDK_CONFIGURATION_MODE === 'online') {
+    return IncodeSdk.startFlow({ sessionConfig });
+  }
+
   if (FLOW_HANDLING === 'step-by-step') {
     const session = await IncodeSdk.setupOnboardingSession({ sessionConfig });
     let lastResult: Awaited<ReturnType<typeof IncodeSdk.startOnboardingSection>> | undefined;
@@ -1091,7 +1137,7 @@ function generatePlan(context, sdkSelection, productOptions) {
   const changes = [
     {
       action: "gitignore_entries",
-      entries: [".env.local", ".incode.local.env", ".npmrc"],
+      entries: [".env.local", ".incode.local.env", ".npmrc", "src/incodeRuntimeConfig.local.ts"],
       file: ".gitignore",
       title: "Keep local SDK credentials out of source control",
     },
@@ -1145,6 +1191,12 @@ function generatePlan(context, sdkSelection, productOptions) {
       file: "src/incodeRuntimeConfig.ts",
       title: "Generate non-secret runtime defaults",
     },
+    {
+      action: "write_file",
+      content: createLocalRuntimeConfigFile(productOptions),
+      file: "src/incodeRuntimeConfig.local.ts",
+      title: "Generate ignored local runtime credential defaults",
+    },
     {
       action: "write_file",
       content: createExampleFile(),
@@ -1251,7 +1303,6 @@ function printPlan(context, plan, options) {
     console.log(`Dashboard flow URL: ${product.dashboardUrl || "not provided"}`);
     console.log(`Dashboard environment: ${labelForApiUrl(product.apiUrl)}`);
     console.log(`Configuration ID: ${product.configurationId || "not inferred"}`);
-    console.log("Dashboard flow config: will be fetched by API when the flow-config endpoint is connected.");
   }
   console.log(`IDV preset: ${product.idv}`);
   console.log(`Flow handling: ${product.flowHandling}`);
@@ -1261,10 +1312,10 @@ function printPlan(context, plan, options) {
   console.log(`Feature deps: ${featureDeps.join(", ") || "none"}`);
   console.log("");
   console.log(
-    "Secrets are never written to generated TypeScript, Gradle, Podfile, or README files.",
+    "Secrets are never written to Gradle, Podfile, README, or committed generated TypeScript files.",
   );
   console.log(
-    "When --apply receives tokens, they are written only to ignored local files: .env.local and .npmrc.",
+    "When --apply receives tokens, they are written only to ignored local files: .env.local, .npmrc, and src/incodeRuntimeConfig.local.ts.",
   );
   console.log("");
   console.log(options.apply ? "Applying changes:" : "Planned changes:");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@incode-sdks/incode-integrate",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "CLI integration auditor and fixer for adding the Incode React Native SDK to client apps.",
   "main": "agent.js",
   "bin": {