@hiofu/apply-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,173 @@
+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.
+
+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

package/README.md

@@ -0,0 +1,420 @@
+# @hiofu/apply-sdk
+
+Browser SDK for HIOFU's Apply with HSP1 flow.
+
+It gives partner job boards, ATS products, and employer career sites a full candidate handoff flow:
+
+- OAuth 2.0 Authorization Code with PKCE
+- consented HSP1 variation review inside the popup
+- immutable application snapshot creation
+- idempotent application submission to HIOFU
+- structured response payload for immediate partner-side handling
+
+## Install
+
+The SDK is a private package. Partners must be granted registry access before
+installing it.
+
+```sh
+npm config set @hiofu:registry https://registry.npmjs.org/
+npm config set //registry.npmjs.org/:_authToken $HIOFU_NPM_TOKEN
+```
+
+```sh
+npm install @hiofu/apply-sdk
+```
+
+### Private preview (if not public yet)
+
+If you received a private access token from HIOFU, add it to your project-level `.npmrc` so `npm install` can fetch the package:
+
+```ini
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+@hiofu:registry=https://registry.npmjs.org/
+```
+
+Then install as usual (with `NPM_TOKEN` set in your environment or CI).
+
+## Quick Start
+
+Use sandbox keys for fake CV/HSP1 testing and live keys only after Hiofu grants
+production access.
+
+```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.applicationId, result.status);
+  },
+  onError(error) {
+    console.error(error.code, error.correlationId, error.message);
+  },
+});
+
+const result = await hiofu.apply({
+  externalJobId: "job_123",
+  externalEmployerId: "emp_456",
+  role: {
+    title: "Senior Engineer",
+    locations: ["London", "Remote"],
+    dimensions: { department: "Engineering" },
+  },
+  idempotencyKey: "apply_attempt_01JXYZ...",
+});
+
+console.log(result.applicationId);
+console.log(result.hiofuRoleId);
+console.log(result.raw.snapshot);
+```
+
+## Configuration
+
+`createApplyClient` is the recommended partner API. It resolves the correct Hiofu URLs from `environment` 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.
+- `storage` (default `memory`): Token storage, either `memory` (cleared on reload) or `session` (persists for the browser session).
+- `scopes` / `applyScopes` (optional): Default scopes for `authorize()` / `apply()`.
+- `popupOptions.timeoutMs` (default 300_000): Popup wait limit in milliseconds.
+- `onComplete(result)`: Receives the normalized apply result.
+- `onCancel(context)`: Receives explicit user-cancel, popup-close, and timeout events.
+- `onError(error)`: Receives a typed `HiofuApplyError`.
+- `onEvent(event)`: Lifecycle hook for telemetry/UX.
+
+`HiofuClient` remains available as the lower-level compatibility API using `clientId`, `hiofuOrigin`, and `apiBase`.
+
+### 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.
+
+```ts
+const isSandbox = process.env.NODE_ENV !== "production"; // or your own flag
+
+const hiofu = createApplyClient({
+  environment: isSandbox ? "sandbox" : "production",
+  publicKey: isSandbox ? "pk_test_xxx" : "pk_live_xxx",
+  redirectUri: `${window.location.origin}/oauth/callback.html`,
+});
+```
+
+## React
+
+```tsx
+import { HiofuProvider, useHiofuApply } 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>
+  );
+}
+
+function ApplyButton() {
+  const { apply, status, error, result } = useHiofuApply();
+
+  return (
+    <button
+      disabled={status === "authorising" || status === "submitting"}
+      onClick={() =>
+        apply({
+          jobId: "job_123",
+          jobTitle: "Senior Engineer",
+          employerId: "emp_456",
+          employerName: "Acme Inc",
+          role: {
+            externalRoleId: "job_123",
+            externalEmployerId: "emp_456",
+            title: "Senior Engineer",
+          },
+        })
+      }
+    >
+      {status === "submitting"
+        ? "Submitting…"
+        : status === "authorising"
+          ? "Authorising…"
+          : status === "success"
+            ? "Submitted"
+            : "Apply with HIOFU"}
+    </button>
+  );
+}
+```
+
+### Error-aware button UX
+
+```tsx
+function ApplyButton() {
+  const { apply, status, error, result, reset } = useHiofuApply();
+  return (
+    <div>
+      <button
+        disabled={status === "authorising" || status === "submitting"}
+        onClick={async () => {
+          try {
+            await apply({
+              jobId: "job_123",
+              jobTitle: "Senior Engineer",
+              employerId: "emp_456",
+              employerName: "Acme Inc",
+            });
+          } catch {}
+        }}
+      >
+        {status === "submitting"
+          ? "Submitting…"
+          : status === "authorising"
+            ? "Authorising…"
+            : status === "success"
+              ? "Submitted"
+              : "Apply with HIOFU"}
+      </button>
+      {status === "error" && <p role="alert">{error?.message}</p>}
+      {status === "success" && <p>Application ID: {result?.application.id}</p>}
+      {(status === "error" || status === "success") && (
+        <button onClick={reset}>Try again</button>
+      )}
+    </div>
+  );
+}
+```
+
+## Hosted Script
+
+```html
+<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"
+>
+  Apply with HIOFU
+</button>
+```
+
+## Environments
+
+| Mode | Client ID | Hiofu origin | API base |
+| --- | --- | --- | --- |
+| Sandbox | `pk_test_*` | `https://sandbox.hiofu.com` | `https://api.sandbox.hiofu.com/api` |
+| Production | `pk_live_*` | `https://hiofu.com` | `https://api.hiofu.com/api` |
+
+`pk_test_*` is for fake sandbox data only. `pk_live_*` is for live candidate
+and employer data after Hiofu production approval.
+
+## Role Capture
+
+Partners should pass their own external role identifiers in `role`. Hiofu maps
+those identifiers to an internal organization and role before an application is
+created. If the role is not mapped, the API rejects the submit request with a
+role mapping error and no application is created.
+
+```ts
+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",
+    description: "Build user-facing product surfaces.",
+    locations: ["London", "Remote"],
+  },
+});
+```
+
+## Callback Handling
+
+Register a callback page (e.g. `https://jobs.example.com/oauth/callback.html`) in your HIOFU partner settings. The page should relay the OAuth result back to the opener. Minimal example:
+
+```html
+<!doctype html>
+<html lang="en">
+  <meta charset="UTF-8" />
+  <title>Returning…</title>
+  <body>
+    Returning you to the partner site…
+    <script>
+      (() => {
+        const p = new URLSearchParams(window.location.search);
+        const payload = {
+          type: "hiofu_oauth",
+          code: p.get("code"),
+          state: p.get("state"),
+          error: p.get("error"),
+          variationId: p.get("variation_id"),
+        };
+        if (window.opener) {
+          try {
+            window.opener.postMessage(payload, window.location.origin);
+          } catch {}
+        }
+        try {
+          if (typeof BroadcastChannel !== "undefined") {
+            const ch = new BroadcastChannel("hiofu_oauth");
+            ch.postMessage(payload);
+            ch.close();
+          }
+        } catch {}
+        try {
+          localStorage.setItem("hiofu_oauth_result", JSON.stringify(payload));
+        } catch {}
+        setTimeout(() => {
+          try {
+            window.close();
+          } catch {}
+        }, 150);
+      })();
+    </script>
+  </body>
+</html>
+```
+
+## Scopes
+
+- `profile.basic`: minimal profile summary intended for partner-side apply UX
+- `profile.full`: sanitised HSP1 profile summary including skills and redacted work/education history
+- `evidence.read`: evidence titles, types, and aggregate trust signals
+- `applications.write`: submit an application on the candidate's behalf
+- `passport.snapshot`: create and return an immutable, partner-safe hiring snapshot with summary previews
+
+## Apply Flow Behaviour
+
+`apply()` requests the minimal application bundle by default:
+
+- `applications.write`
+- `passport.snapshot`
+
+If no `variationId` is passed, the popup asks the candidate which HSP1 view to share and carries that exact selection through the final application submission.
+
+Returned payload highlights:
+
+- `application`: the HIOFU application record
+- `sharedView`, `versionNumber`, and `snapshot`: immutable snapshot context plus safe hiring previews
+- `profile`, `evidence`, `snapshot`: minimised partner-consumable response data based on granted scopes
+- `delivery`: whether HIOFU also queued webhook delivery or returned response-only data
+- `idempotencyKey`: the exact key used for this apply attempt
+
+## Security Notes
+
+- Register a partner-owned callback page like `https://jobs.example.com/oauth/callback.html` and pass it explicitly as `redirectUri`.
+- Browser integrations receive a short-lived access token only through the SDK runtime. Refresh tokens are never exposed to partner UI code.
+- The SDK does not inject third-party fonts or global styles into partner pages. Keep typography ownership inside your app shell.
+- Do not log raw application payloads in production UIs.
+- Pass a stable partner-generated `idempotencyKey` when you already have an application-attempt identifier.
+- If you omit `idempotencyKey`, the SDK generates one for you and mirrors it into both the request header and body.
+- The SDK defaults to in-memory token storage. Only opt into session storage if your threat model explicitly allows it.
+- The popup times out after 5 minutes by default. Override `authorizeTimeoutMs` if your flow needs a different review window.
+
+## Events
+
+Subscribe to SDK lifecycle events when you want to build custom UX around the flow:
+
+- `popup_opened`
+- `popup_result_received`
+- `popup_closed`
+- `token_issued`
+- `apply_started`
+- `apply_submitting`
+- `apply_success`
+- `apply_error`
+
+## Brand Helpers
+
+The SDK exports HIOFU brand constants and an inline SVG mark:
+
+```ts
+import {
+  HIOFU_BRAND_COLOR,
+  HIOFU_BUTTON_LABEL,
+  HIOFU_WORDMARK,
+  HIOFU_TAGLINE,
+  hiofuLogoSvg,
+} from "@hiofu/apply-sdk";
+```
+
+Examples in this repo load Geist explicitly. Production partner apps should choose their own font-loading strategy rather than relying on the SDK to inject one.
+
+## Examples
+
+See [`partner-examples/`](../partner-examples) for working integrations: Next.js, static HTML, vanilla TS SPA, and webhook receiver examples.
+
+## Errors
+
+- `HiofuConfigurationError`: Thrown before network requests when SDK config is invalid, including `hiofu.environment_mismatch`.
+- `HiofuApiError`: Thrown for HTTP errors from the partner API. Includes `status` and parsed `body` when available.
+- Popup errors: "Popup blocked" (user agent blocks window.open), "Authorization timed out" (no result within `authorizeTimeoutMs`).
+
+```ts
+import {
+  HiofuClient,
+  HiofuApiError,
+  HiofuConfigurationError,
+} from "@hiofu/apply-sdk";
+
+const hiofu = new HiofuClient({
+  clientId: "pk_live_xxx",
+  redirectUri: `${location.origin}/oauth/callback.html`,
+});
+
+try {
+  const res = await hiofu.apply({
+    jobId: "job_123",
+    jobTitle: "Senior Engineer",
+    employerId: "emp_456",
+    employerName: "Acme Inc",
+    idempotencyKey: "apply_attempt_01JXYZ…",
+  });
+  console.log(res.application.id);
+} catch (err) {
+  if (err instanceof HiofuConfigurationError) {
+    console.warn("SDK config error", err.code, err.details);
+  } else if (err instanceof HiofuApiError) {
+    // Inspect HTTP layer
+    console.warn("API error", err.status, err.body);
+    if (err.status === 401) {
+      // Not authorised; ask user to try again
+    }
+    if (err.status === 409) {
+      // Duplicate idempotency key; treat as success or fetch the prior result
+    }
+  } else {
+    // Popup blocked / timed out / generic runtime error
+    console.error(err.message);
+  }
+}
+```