@hiofu/apply-sdk 0.1.5 → 0.1.6-beta.0

package/README.md

@@ -18,50 +18,51 @@ npm install @hiofu/apply-sdk
 
 ## Quick Start
 
-Use sandbox keys for testing and live keys only after HIOFU grants
-production access.
+### React (simplest)
+
+```tsx
+import { HiofuApplyButton } from "@hiofu/apply-sdk/react";
+
+export function ApplyButton({ jobId, jobTitle }) {
+  return (
+    <HiofuApplyButton
+      clientId={process.env.NEXT_PUBLIC_HIOFU_KEY}
+      variant="primary"
+      options={{ jobId, jobTitle }}
+    />
+  );
+}
+```
+
+The SDK infers sandbox/production from the key prefix and uses the
+HIOFU-hosted callback by default. No extra config needed.
+
+### Vanilla JS
 
 ```ts
 import { createApplyClient } from "@hiofu/apply-sdk";
 
 const hiofu = createApplyClient({
-  environment: "sandbox",
   publicKey: "pk_test_xxx",
-  redirectUri: "https://jobs.example.com/oauth/callback.html",
-  onComplete(result) {
-    console.log(result.application.id, result.application.status);
-  },
-  onError(error) {
-    console.error(error.code, error.correlationId, error.message);
-  },
 });
 
 const result = await hiofu.apply({
   jobId: "job_123",
-  jobTitle: "Senior Engineer",
-  employerId: "emp_456",
-  employerName: "Acme Inc",
-  role: {
-    externalRoleId: "job_123",
-    externalEmployerId: "emp_456",
-    title: "Senior Engineer",
-    locations: ["London", "Remote"],
-    metadata: { department: "Engineering" },
-  },
+  role: { title: "Senior Engineer" },
   idempotencyKey: "apply_attempt_01JXYZ...",
 });
 
-console.log(result.application.id);
-console.log(result.snapshot?.trustBand);
+console.log(result.applicationId);
 ```
 
 ## Configuration
 
-`createApplyClient` is the recommended API. It resolves the correct HIOFU URLs from `environment` and rejects key/environment mismatches before opening the popup.
+`createApplyClient` resolves the correct HIOFU URLs from the key prefix and
+rejects key/environment mismatches before opening the popup.
 
-- `environment` (required): `sandbox` or `production`.
 - `publicKey` (required): Your publishable key, e.g. `pk_test_…` or `pk_live_…`.
-- `redirectUri` (required): One of your registered callback URLs.
+- `environment` (optional): Inferred from key prefix. Override with `"sandbox"` or `"production"` if needed.
+- `redirectUri` (optional): Defaults to the HIOFU-hosted callback. Set this only if you host your own callback page.
 - `storage` (default `memory`): Token storage, either `memory` (cleared on reload) or `session` (persists the access token for the browser session; refresh tokens are not persisted in browser storage).
 - `scopes` / `applyScopes` (optional): Default scopes for `authorize()` / `apply()`.
 - `popupOptions.timeoutMs` (default 300_000): Popup wait limit in milliseconds.
@@ -72,13 +73,15 @@ console.log(result.snapshot?.trustBand);
 
 `HiofuClient` remains available as the lower-level compatibility API using `clientId`, `hiofuOrigin`, and `apiBase`.
 
-## Manage Setup From The SDK
+## Optional Backend Setup Automation
 
 If your team prefers automation over the HIOFU Developer settings UI,
 the same setup actions are available from the management client.
 
-Use this from your backend or internal tooling. The access token should
-stay on trusted infrastructure.
+The public browser Apply flow does not need an employer access token.
+Use this management client only from your backend or internal tooling
+when you want to automate setup. The access token should stay on trusted
+infrastructure and must never be exposed to browser code.
 
 ```ts
 import { createManagementClient } from "@hiofu/apply-sdk";
@@ -102,16 +105,11 @@ const role = await management.createRole({
 await management.updateRoleStatus(role.id, "hiring");
 ```
 
-### Issue the publishable key, register the callback, and save the route
+### Issue the publishable key and save the route
 
 ```ts
 await management.issuePublishableKey();
 
-await management.addRedirectUri({
-  mode: "test",
-  uri: "https://jobs.example.com/oauth/callback-shim.html",
-});
-
 await management.saveRoleMapping({
   mode: "test",
   externalRoleId: "job_123",
@@ -119,6 +117,16 @@ await management.saveRoleMapping({
 });
 ```
 
+Register a callback URI only if you override the SDK's HIOFU-hosted callback
+with your own `redirectUri`.
+
+```ts
+await management.addRedirectUri({
+  mode: "test",
+  uri: "https://jobs.example.com/oauth/callback.html",
+});
+```
+
 ### Update or remove setup later
 
 ```ts
@@ -152,62 +160,41 @@ HIOFU Developer settings UI:
 
 ### Sandbox vs Production
 
-Switch environments by key and base URLs. The SDK rejects mismatches before
-opening the popup: `pk_test_*` must use sandbox URLs, and `pk_live_*` must use
-production URLs.
+Switch environments by key. The SDK infers the correct URLs from the prefix.
 
 ```ts
-const isSandbox = process.env.NODE_ENV !== "production"; // or your own flag
+const isSandbox = process.env.NODE_ENV !== "production";
 
 const hiofu = createApplyClient({
-  environment: isSandbox ? "sandbox" : "production",
   publicKey: isSandbox ? "pk_test_xxx" : "pk_live_xxx",
-  redirectUri: `${window.location.origin}/oauth/callback.html`,
 });
 ```
 
 ## React
 
+### Standalone button (simplest)
+
 ```tsx
-import { HiofuApplyButton, HiofuProvider } from "@hiofu/apply-sdk/react";
+import { HiofuApplyButton } from "@hiofu/apply-sdk/react";
 
-export default function App() {
-  return (
-    <HiofuProvider
-      config={{
-        clientId: "pk_test_xxx",
-        hiofuOrigin: "https://sandbox.hiofu.com",
-        apiBase: "https://api.sandbox.hiofu.com/api",
-        redirectUri: "https://jobs.example.com/oauth/callback.html",
-        // Optional extras with sensible defaults
-        // storage: "session",
-        // applyScopes: ["applications.write", "passport.snapshot"],
-        // onEvent: (e) => console.debug("hiofu", e),
-      }}
-    >
-      <ApplyButton />
-    </HiofuProvider>
-  );
-}
+<HiofuApplyButton
+  clientId="pk_test_xxx"
+  variant="primary"
+  options={{ jobId: "job_123", jobTitle: "Senior Engineer" }}
+/>
+```
 
-function ApplyButton() {
-  return (
-    <HiofuApplyButton
-      variant="primary"
-      options={{
-        jobId: "job_123",
-        jobTitle: "Senior Engineer",
-        employerId: "emp_456",
-        employerName: "Acme Inc",
-        role: {
-          externalRoleId: "job_123",
-          externalEmployerId: "emp_456",
-          title: "Senior Engineer",
-        },
-      }}
-    />
-  );
-}
+No provider needed for a single button. The SDK infers everything from the key.
+
+### With provider (multiple buttons sharing config)
+
+```tsx
+import { HiofuApplyButton, HiofuProvider } from "@hiofu/apply-sdk/react";
+
+<HiofuProvider config={{ clientId: "pk_test_xxx" }}>
+  <HiofuApplyButton options={{ jobId: "job_1", jobTitle: "Role A" }} />
+  <HiofuApplyButton options={{ jobId: "job_2", jobTitle: "Role B" }} />
+</HiofuProvider>
 ```
 
 `HiofuApplyButton` ships three variants: `primary`, `secondary`, and `ghost`.
@@ -257,19 +244,13 @@ function ApplyButton() {
 <script
   src="https://cdn.hiofu.com/apply-sdk.global.js"
   data-client-id="pk_test_xxx"
-  data-hiofu-origin="https://sandbox.hiofu.com"
-  data-api-base="https://api.sandbox.hiofu.com/api"
-  data-redirect-uri="https://jobs.example.com/oauth/callback.html"
 ></script>
 
 <button
   data-hiofu-apply
   data-job-id="job_123"
   data-job-title="Senior Engineer"
-  data-employer-id="emp_456"
   data-employer-name="Acme Inc"
-  data-external-role-id="job_123"
-  data-external-employer-id="emp_456"
   data-role-department="Engineering"
   data-role-locations="London,Remote"
 >
@@ -321,9 +302,15 @@ await hiofu.apply({
 });
 ```
 
-## Callback Handling
+## Custom Callback Handling
+
+Most integrations do not need a callback page. When `redirectUri` is omitted,
+the SDK uses the HIOFU-hosted callback for the key's environment.
 
-Register your callback page (e.g. `https://jobs.example.com/oauth/callback.html`) in HIOFU Developer settings. Do not register callback URLs on domains you do not control. The page should relay the OAuth result back to the opener. Minimal example:
+Only host your own callback when you have a specific same-origin requirement.
+In that case, register the exact callback URL in HIOFU Developer settings and
+pass it as `redirectUri`. Do not register callback URLs on domains you do not
+control. The page should relay the OAuth result back to the opener:
 
 ```html
 <!doctype html>
@@ -395,7 +382,7 @@ Returned payload highlights:
 
 ## Security Notes
 
-- Register your callback page (e.g. `https://jobs.example.com/oauth/callback.html`) and pass it explicitly as `redirectUri`; never use domains you do not control.
+- Prefer the HIOFU-hosted callback. If you host your own callback page, register only domains you control and pass the URL explicitly as `redirectUri`.
 - Browser integrations receive a short-lived access token only through the SDK runtime. Refresh tokens are never exposed to your UI code.
 - The SDK does not inject third-party fonts or global styles into your pages. Keep typography ownership inside your app shell.
 - Do not log raw application payloads in production UIs.
@@ -452,7 +439,6 @@ import {
 
 const hiofu = new HiofuClient({
   clientId: "pk_live_xxx",
-  redirectUri: `${location.origin}/oauth/callback.html`,
 });
 
 try {

package/dist/{chunk-MFY3F4OY.js → chunk-7JEEWWEX.js}

@@ -338,9 +338,6 @@ var HiofuPopupError = class extends Error {
 function resolveRedirectUri(config, hiofuOrigin) {
   if (config.redirectUri) return config.redirectUri;
   const hiofuBaseOrigin = new URL(hiofuOrigin).origin;
-  if (typeof window !== "undefined" && window.location.origin && window.location.origin !== hiofuBaseOrigin) {
-    return new URL("/oauth/callback.html", window.location.origin).toString();
-  }
   return `${hiofuBaseOrigin}/oauth/callback-shim`;
 }
 async function authorize(config, scopes, context, callbacks) {
@@ -354,6 +351,9 @@ async function authorize(config, scopes, context, callbacks) {
   const url = new URL(`${hiofuOrigin}/oauth/consent`);
   url.searchParams.set("client_id", config.clientId);
   url.searchParams.set("redirect_uri", redirectUri);
+  if (window.location?.origin) {
+    url.searchParams.set("opener_origin", window.location.origin);
+  }
   url.searchParams.set("scope", scopes.join(" "));
   url.searchParams.set("state", state);
   url.searchParams.set("code_challenge", challenge);
@@ -389,6 +389,7 @@ async function authorize(config, scopes, context, callbacks) {
     let channel = null;
     let openerLostAttention = false;
     let openerRegainedAttention = false;
+    let popupClosedAt = null;
     const cleanup = () => {
       settled = true;
       window.removeEventListener("message", onMessage);
@@ -538,14 +539,28 @@ async function authorize(config, scopes, context, callbacks) {
         }
       } catch {
       }
-      if (popup.closed && openerRegainedAttention) {
+      if (popup.closed) {
+        popupClosedAt ?? (popupClosedAt = Date.now());
+      } else {
+        popupClosedAt = null;
+      }
+      const canTreatAsClosed = popup.closed && popupClosedAt !== null && openerRegainedAttention && document.hasFocus() && Date.now() - popupClosedAt > 5e3;
+      if (canTreatAsClosed) {
         try {
           const raw = localStorage.getItem("hiofu_oauth_result");
-          if (raw) {
-            handleResult(JSON.parse(raw), "close_check");
-          }
+          if (raw) handleResult(JSON.parse(raw), "close_check");
         } catch {
         }
+        if (!settled) {
+          cleanup();
+          callbacks?.onPopupClosed?.("user_closed");
+          reject(
+            new HiofuPopupError(
+              "user_closed",
+              "Authorization popup closed before HIOFU could complete the request. Please try again."
+            )
+          );
+        }
       }
     }, 500);
     overallTimeout = window.setTimeout(() => {
@@ -699,10 +714,13 @@ var HiofuClient = class {
     if (!config.clientId) {
       throw new Error("HiofuClient: clientId is required");
     }
+    const isSandboxKey = config.clientId.startsWith("pk_test_");
+    const defaultOrigin = isSandboxKey ? "https://sandbox.hiofu.com" : "https://hiofu.com";
+    const defaultApiBase = isSandboxKey ? "https://api.sandbox.hiofu.com/api" : "https://api.hiofu.com/api";
     this.config = {
       ...config,
-      hiofuOrigin: config.hiofuOrigin ?? "https://hiofu.com",
-      apiBase: config.apiBase ?? "https://api.hiofu.com/api",
+      hiofuOrigin: config.hiofuOrigin ?? defaultOrigin,
+      apiBase: config.apiBase ?? defaultApiBase,
       storage: config.storage ?? "memory",
       authorizeTimeoutMs: config.authorizeTimeoutMs ?? 5 * 6e4
     };
@@ -824,12 +842,21 @@ var HiofuClient = class {
         idempotencyKey,
         variationId: selectedVariationId
       });
+      const resolvedRole = opts.role ? {
+        ...opts.role,
+        externalRoleId: opts.role.externalRoleId || opts.jobId,
+        title: opts.role.title || opts.jobTitle,
+        externalEmployerId: opts.role.externalEmployerId || opts.employerId || void 0
+      } : {
+        externalRoleId: opts.jobId,
+        title: opts.jobTitle
+      };
       const json = await submitApplication(this.config, access, {
         jobId: opts.jobId,
         jobTitle: opts.jobTitle,
         employerId: opts.employerId,
         employerName: opts.employerName,
-        role: opts.role,
+        role: resolvedRole,
         variationId: selectedVariationId ?? void 0,
         idempotencyKey
       });

package/dist/{client-Ct5xyQMk.d.cts → client-7yPni-fK.d.cts}

@@ -11,8 +11,8 @@ interface HiofuConfig {
     /** Optional default scopes for `apply()`. */
     applyScopes?: HiofuScope[];
     /** Where the popup will redirect on success. Must be one of the partner's
-     *  registered URIs. If omitted in the browser, the SDK falls back to a
-     *  same-origin `/oauth/callback.html` page when possible. */
+     *  registered URIs. If omitted, the SDK uses the HIOFU-hosted callback for
+     *  the selected environment. */
     redirectUri?: string;
     /** Where to store the access token client-side. */
     storage?: "session" | "memory";
@@ -26,11 +26,12 @@ interface HiofuTokenSet {
     scopes: HiofuScope[];
 }
 interface HiofuApplyRole {
-    /** Partner-owned stable role/job identifier. */
-    externalRoleId: string;
+    /** Partner-owned stable role/job identifier. Defaults to jobId when omitted. */
+    externalRoleId?: string;
     /** Partner-owned stable employer/company identifier, optional for direct HIOFU-domain integrations. */
     externalEmployerId?: string;
-    title: string;
+    /** Defaults to jobTitle when omitted. */
+    title?: string;
     description?: string;
     department?: string;
     locations?: string[];
@@ -424,4 +425,4 @@ declare class HiofuClient {
     logout(): Promise<void>;
 }
 
-export { DEFAULT_APPLY_SCOPES as D, HiofuClient as H, type HiofuScope as a, type HiofuApplyResult as b, type HiofuConfig as c, type HiofuEvent as d, type HiofuManagementConfig as e, type HiofuManagementListRolesParams as f, type HiofuManagementPaginatedResult as g, type HiofuManagementRoleListItem as h, type HiofuManagementRole as i, type HiofuManagementCreateRoleInput as j, type HiofuManagementUpdateRoleInput as k, type HiofuManagementRoleStatus as l, type HiofuManagementDeveloperSettings as m, type HiofuManagementSaveRoleMappingInput as n, type HiofuManagementAddRedirectUriInput as o, type HiofuApplyOptions as p, type HiofuTokenSet as q, DEFAULT_AUTHORIZE_SCOPES as r, type HiofuApplyRole as s, type HiofuManagementEnvironment as t, type HiofuManagementEnvironmentMode as u, type HiofuManagementRedirectUri as v, type HiofuManagementRoleDimension as w, type HiofuManagementRoleDimensionSkill as x, type HiofuManagementRoleMapping as y, type HiofuPartner as z };
+export { DEFAULT_APPLY_SCOPES as D, type HiofuApplyOptions as H, DEFAULT_AUTHORIZE_SCOPES as a, type HiofuApplyResult as b, type HiofuApplyRole as c, HiofuClient as d, type HiofuConfig as e, type HiofuEvent as f, type HiofuManagementAddRedirectUriInput as g, type HiofuManagementConfig as h, type HiofuManagementCreateRoleInput as i, type HiofuManagementDeveloperSettings as j, type HiofuManagementEnvironment as k, type HiofuManagementEnvironmentMode as l, type HiofuManagementListRolesParams as m, type HiofuManagementPaginatedResult as n, type HiofuManagementRedirectUri as o, type HiofuManagementRole as p, type HiofuManagementRoleDimension as q, type HiofuManagementRoleDimensionSkill as r, type HiofuManagementRoleListItem as s, type HiofuManagementRoleMapping as t, type HiofuManagementRoleStatus as u, type HiofuManagementSaveRoleMappingInput as v, type HiofuManagementUpdateRoleInput as w, type HiofuPartner as x, type HiofuScope as y, type HiofuTokenSet as z };

package/dist/{client-Ct5xyQMk.d.ts → client-7yPni-fK.d.ts}

@@ -11,8 +11,8 @@ interface HiofuConfig {
     /** Optional default scopes for `apply()`. */
     applyScopes?: HiofuScope[];
     /** Where the popup will redirect on success. Must be one of the partner's
-     *  registered URIs. If omitted in the browser, the SDK falls back to a
-     *  same-origin `/oauth/callback.html` page when possible. */
+     *  registered URIs. If omitted, the SDK uses the HIOFU-hosted callback for
+     *  the selected environment. */
     redirectUri?: string;
     /** Where to store the access token client-side. */
     storage?: "session" | "memory";
@@ -26,11 +26,12 @@ interface HiofuTokenSet {
     scopes: HiofuScope[];
 }
 interface HiofuApplyRole {
-    /** Partner-owned stable role/job identifier. */
-    externalRoleId: string;
+    /** Partner-owned stable role/job identifier. Defaults to jobId when omitted. */
+    externalRoleId?: string;
     /** Partner-owned stable employer/company identifier, optional for direct HIOFU-domain integrations. */
     externalEmployerId?: string;
-    title: string;
+    /** Defaults to jobTitle when omitted. */
+    title?: string;
     description?: string;
     department?: string;
     locations?: string[];
@@ -424,4 +425,4 @@ declare class HiofuClient {
     logout(): Promise<void>;
 }
 
-export { DEFAULT_APPLY_SCOPES as D, HiofuClient as H, type HiofuScope as a, type HiofuApplyResult as b, type HiofuConfig as c, type HiofuEvent as d, type HiofuManagementConfig as e, type HiofuManagementListRolesParams as f, type HiofuManagementPaginatedResult as g, type HiofuManagementRoleListItem as h, type HiofuManagementRole as i, type HiofuManagementCreateRoleInput as j, type HiofuManagementUpdateRoleInput as k, type HiofuManagementRoleStatus as l, type HiofuManagementDeveloperSettings as m, type HiofuManagementSaveRoleMappingInput as n, type HiofuManagementAddRedirectUriInput as o, type HiofuApplyOptions as p, type HiofuTokenSet as q, DEFAULT_AUTHORIZE_SCOPES as r, type HiofuApplyRole as s, type HiofuManagementEnvironment as t, type HiofuManagementEnvironmentMode as u, type HiofuManagementRedirectUri as v, type HiofuManagementRoleDimension as w, type HiofuManagementRoleDimensionSkill as x, type HiofuManagementRoleMapping as y, type HiofuPartner as z };
+export { DEFAULT_APPLY_SCOPES as D, type HiofuApplyOptions as H, DEFAULT_AUTHORIZE_SCOPES as a, type HiofuApplyResult as b, type HiofuApplyRole as c, HiofuClient as d, type HiofuConfig as e, type HiofuEvent as f, type HiofuManagementAddRedirectUriInput as g, type HiofuManagementConfig as h, type HiofuManagementCreateRoleInput as i, type HiofuManagementDeveloperSettings as j, type HiofuManagementEnvironment as k, type HiofuManagementEnvironmentMode as l, type HiofuManagementListRolesParams as m, type HiofuManagementPaginatedResult as n, type HiofuManagementRedirectUri as o, type HiofuManagementRole as p, type HiofuManagementRoleDimension as q, type HiofuManagementRoleDimensionSkill as r, type HiofuManagementRoleListItem as s, type HiofuManagementRoleMapping as t, type HiofuManagementRoleStatus as u, type HiofuManagementSaveRoleMappingInput as v, type HiofuManagementUpdateRoleInput as w, type HiofuPartner as x, type HiofuScope as y, type HiofuTokenSet as z };

package/dist/index.cjs

@@ -385,9 +385,6 @@ var HiofuPopupError = class extends Error {
 function resolveRedirectUri(config, hiofuOrigin) {
   if (config.redirectUri) return config.redirectUri;
   const hiofuBaseOrigin = new URL(hiofuOrigin).origin;
-  if (typeof window !== "undefined" && window.location.origin && window.location.origin !== hiofuBaseOrigin) {
-    return new URL("/oauth/callback.html", window.location.origin).toString();
-  }
   return `${hiofuBaseOrigin}/oauth/callback-shim`;
 }
 async function authorize(config, scopes, context, callbacks) {
@@ -401,6 +398,9 @@ async function authorize(config, scopes, context, callbacks) {
   const url = new URL(`${hiofuOrigin}/oauth/consent`);
   url.searchParams.set("client_id", config.clientId);
   url.searchParams.set("redirect_uri", redirectUri);
+  if (window.location?.origin) {
+    url.searchParams.set("opener_origin", window.location.origin);
+  }
   url.searchParams.set("scope", scopes.join(" "));
   url.searchParams.set("state", state);
   url.searchParams.set("code_challenge", challenge);
@@ -436,6 +436,7 @@ async function authorize(config, scopes, context, callbacks) {
     let channel = null;
     let openerLostAttention = false;
     let openerRegainedAttention = false;
+    let popupClosedAt = null;
     const cleanup = () => {
       settled = true;
       window.removeEventListener("message", onMessage);
@@ -585,14 +586,28 @@ async function authorize(config, scopes, context, callbacks) {
         }
       } catch {
       }
-      if (popup.closed && openerRegainedAttention) {
+      if (popup.closed) {
+        popupClosedAt ?? (popupClosedAt = Date.now());
+      } else {
+        popupClosedAt = null;
+      }
+      const canTreatAsClosed = popup.closed && popupClosedAt !== null && openerRegainedAttention && document.hasFocus() && Date.now() - popupClosedAt > 5e3;
+      if (canTreatAsClosed) {
         try {
           const raw = localStorage.getItem("hiofu_oauth_result");
-          if (raw) {
-            handleResult(JSON.parse(raw), "close_check");
-          }
+          if (raw) handleResult(JSON.parse(raw), "close_check");
         } catch {
         }
+        if (!settled) {
+          cleanup();
+          callbacks?.onPopupClosed?.("user_closed");
+          reject(
+            new HiofuPopupError(
+              "user_closed",
+              "Authorization popup closed before HIOFU could complete the request. Please try again."
+            )
+          );
+        }
       }
     }, 500);
     overallTimeout = window.setTimeout(() => {
@@ -746,10 +761,13 @@ var HiofuClient = class {
     if (!config.clientId) {
       throw new Error("HiofuClient: clientId is required");
     }
+    const isSandboxKey = config.clientId.startsWith("pk_test_");
+    const defaultOrigin = isSandboxKey ? "https://sandbox.hiofu.com" : "https://hiofu.com";
+    const defaultApiBase = isSandboxKey ? "https://api.sandbox.hiofu.com/api" : "https://api.hiofu.com/api";
     this.config = {
       ...config,
-      hiofuOrigin: config.hiofuOrigin ?? "https://hiofu.com",
-      apiBase: config.apiBase ?? "https://api.hiofu.com/api",
+      hiofuOrigin: config.hiofuOrigin ?? defaultOrigin,
+      apiBase: config.apiBase ?? defaultApiBase,
       storage: config.storage ?? "memory",
       authorizeTimeoutMs: config.authorizeTimeoutMs ?? 5 * 6e4
     };
@@ -871,12 +889,21 @@ var HiofuClient = class {
         idempotencyKey,
         variationId: selectedVariationId
       });
+      const resolvedRole = opts.role ? {
+        ...opts.role,
+        externalRoleId: opts.role.externalRoleId || opts.jobId,
+        title: opts.role.title || opts.jobTitle,
+        externalEmployerId: opts.role.externalEmployerId || opts.employerId || void 0
+      } : {
+        externalRoleId: opts.jobId,
+        title: opts.jobTitle
+      };
       const json = await submitApplication(this.config, access, {
         jobId: opts.jobId,
         jobTitle: opts.jobTitle,
         employerId: opts.employerId,
         employerName: opts.employerName,
-        role: opts.role,
+        role: resolvedRole,
         variationId: selectedVariationId ?? void 0,
         idempotencyKey
       });
@@ -1078,6 +1105,11 @@ var HiofuApplyError = class extends Error {
     this.cause = args.cause;
   }
 };
+function inferEnvironment(publicKey) {
+  if (publicKey.startsWith("pk_test_")) return "sandbox";
+  if (publicKey.startsWith("pk_live_")) return "production";
+  return null;
+}
 var ENDPOINTS = {
   sandbox: {
     hiofuOrigin: "https://sandbox.hiofu.com",
@@ -1110,15 +1142,24 @@ function assertPublicKey(environment, publicKey) {
   }
 }
 function toApplyOptions(payload) {
+  const jobId = payload.jobId ?? payload.externalJobId;
+  if (!jobId) {
+    throw new HiofuApplyError({
+      code: "configuration_error",
+      message: "HIOFU Apply requires a jobId.",
+      correlationId: createCorrelationId(),
+      retryable: false
+    });
+  }
   const locations = payload.role.locations ?? (payload.role.location ? [payload.role.location] : void 0);
   const options = {
-    jobId: payload.externalJobId,
+    jobId,
     jobTitle: payload.jobTitle ?? payload.role.title,
     scopes: payload.scopes,
     variationId: payload.variationId,
     idempotencyKey: payload.idempotencyKey,
     role: {
-      externalRoleId: payload.externalJobId,
+      externalRoleId: jobId,
       title: payload.role.title,
       description: payload.role.description,
       locations,
@@ -1203,8 +1244,9 @@ function toApplyError(error, correlationId) {
   });
 }
 function createApplyClient(config) {
-  assertPublicKey(config.environment, config.publicKey);
-  const endpoints = ENDPOINTS[config.environment];
+  const resolvedEnvironment = config.environment ?? inferEnvironment(config.publicKey) ?? "sandbox";
+  assertPublicKey(resolvedEnvironment, config.publicKey);
+  const endpoints = ENDPOINTS[resolvedEnvironment];
   const client = new HiofuClient({
     clientId: config.publicKey,
     hiofuOrigin: config.hiofuOrigin ?? endpoints.hiofuOrigin,
@@ -1233,7 +1275,7 @@ function createApplyClient(config) {
         const result = await client.apply(toApplyOptions(payload));
         const normalized = toNormalizedResult(
           result,
-          config.environment,
+          resolvedEnvironment,
           payload.idempotencyKey
         );
         config.onComplete?.(normalized);

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { H as HiofuClient, a as HiofuScope, b as HiofuApplyResult, c as HiofuConfig, d as HiofuEvent, e as HiofuManagementConfig, f as HiofuManagementListRolesParams, g as HiofuManagementPaginatedResult, h as HiofuManagementRoleListItem, i as HiofuManagementRole, j as HiofuManagementCreateRoleInput, k as HiofuManagementUpdateRoleInput, l as HiofuManagementRoleStatus, m as HiofuManagementDeveloperSettings, n as HiofuManagementSaveRoleMappingInput, o as HiofuManagementAddRedirectUriInput, p as HiofuApplyOptions, q as HiofuTokenSet } from './client-Ct5xyQMk.cjs';
-export { D as DEFAULT_APPLY_SCOPES, r as DEFAULT_AUTHORIZE_SCOPES, s as HiofuApplyRole, t as HiofuManagementEnvironment, u as HiofuManagementEnvironmentMode, v as HiofuManagementRedirectUri, w as HiofuManagementRoleDimension, x as HiofuManagementRoleDimensionSkill, y as HiofuManagementRoleMapping, z as HiofuPartner } from './client-Ct5xyQMk.cjs';
+import { d as HiofuClient, y as HiofuScope, b as HiofuApplyResult, e as HiofuConfig, f as HiofuEvent, h as HiofuManagementConfig, m as HiofuManagementListRolesParams, n as HiofuManagementPaginatedResult, s as HiofuManagementRoleListItem, p as HiofuManagementRole, i as HiofuManagementCreateRoleInput, w as HiofuManagementUpdateRoleInput, u as HiofuManagementRoleStatus, j as HiofuManagementDeveloperSettings, v as HiofuManagementSaveRoleMappingInput, g as HiofuManagementAddRedirectUriInput, H as HiofuApplyOptions, z as HiofuTokenSet } from './client-7yPni-fK.cjs';
+export { D as DEFAULT_APPLY_SCOPES, a as DEFAULT_AUTHORIZE_SCOPES, c as HiofuApplyRole, k as HiofuManagementEnvironment, l as HiofuManagementEnvironmentMode, o as HiofuManagementRedirectUri, q as HiofuManagementRoleDimension, r as HiofuManagementRoleDimensionSkill, t as HiofuManagementRoleMapping, x as HiofuPartner } from './client-7yPni-fK.cjs';
 
 /**
  * Scan the document for `[data-hiofu-apply]` buttons and wire them up to call
@@ -48,10 +48,12 @@ declare class HiofuApplyError extends Error {
     });
 }
 interface HiofuCreateApplyClientConfig {
-    environment: HiofuEnvironment;
-    /** Publishable partner key: pk_test_* for sandbox, pk_live_* for production. */
+    /** Inferred from publicKey prefix when omitted. */
+    environment?: HiofuEnvironment;
+    /** Publishable key: pk_test_* for sandbox, pk_live_* for production. */
     publicKey: string;
-    redirectUri: string;
+    /** Defaults to the HIOFU-hosted callback when omitted. */
+    redirectUri?: string;
     scopes?: HiofuScope[];
     applyScopes?: HiofuScope[];
     storage?: HiofuConfig["storage"];
@@ -67,9 +69,12 @@ interface HiofuCreateApplyClientConfig {
     /** Internal/testing override. Partners should use `environment`. */
     apiBase?: string;
 }
-interface HiofuApplyPayload {
+interface HiofuApplyPayloadBase {
     externalEmployerId?: string;
-    externalJobId: string;
+    /**
+     * Backwards-compatible alias for jobId. Prefer jobId in new integrations.
+     */
+    externalJobId?: string;
     role: {
         title: string;
         description?: string;
@@ -88,6 +93,13 @@ interface HiofuApplyPayload {
     scopes?: HiofuScope[];
     partnerTags?: Record<string, string>;
 }
+type HiofuApplyPayload = HiofuApplyPayloadBase & ({
+    jobId: string;
+    externalJobId?: string;
+} | {
+    jobId?: string;
+    externalJobId: string;
+});
 interface HiofuNormalizedApplyResult {
     applicationId: string;
     partnerApplicationId?: string;