@overturo/js 0.0.0-stage → 1.5.2

package/LICENSE

@@ -0,0 +1,201 @@
+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.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+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
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright 2026 Overturo Geneva Association
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,3 +1,392 @@
-# Temporary Holding Version
+> **Release mirror.** This repository is a read-only snapshot of
+> `@overturo/js` 1.5.2, published from Overturo's main
+> development repository. Issues and pull requests are welcome here; accepted
+> changes are ported upstream and appear in the next release snapshot.
+> Security reports: see [SECURITY.md](./SECURITY.md).
 
-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.
+# @overturo/js
+
+**Documentation:** <https://overturo.com/developers/sdks> · **API reference:** <https://overturo.com/developers/openapi>
+
+JavaScript SDK for integrating Overturo consent flows into your application. TypeScript-first, zero runtime dependencies.
+
+## Installation
+
+```bash
+npm install @overturo/js
+```
+
+Or via CDN:
+
+```html
+<script src="https://unpkg.com/@overturo/js/dist/overturo.global.js"></script>
+```
+
+## Quick Start
+
+### Embed a consent flow
+
+```typescript
+import { Overturo } from "@overturo/js";
+
+const overturo = new Overturo({ publishableKey: "pk_live_..." });
+
+const flow = await overturo.consent({
+  flowId: "flw_...",
+  container: "#consent-container",
+  scope: "openid profile email",
+  onComplete: (result) => {
+    console.log("Consent token:", result.consentToken);
+    // Send consentToken to your server for exchange
+  },
+  onCancel: () => {
+    console.log("User cancelled");
+  },
+  onError: (error) => {
+    console.error("Error:", error);
+  },
+});
+
+// Clean up when done
+flow.destroy();
+```
+
+### Embed a signing flow
+
+Cross-border legal signing rides the same delivery layer as consent and approval.
+Mint a signing session server-side, then open it by its signing-slot reference:
+
+```typescript
+const overturo = new Overturo({ publishableKey: "pk_live_..." });
+
+const signing = await overturo.signing.open({
+  signatureRef: "part_...", // this signer's slot in the agreement
+  container: "#signing-container",
+  mode: "embed", // or "popup" / "redirect"
+  onState: (payload) => {
+    // Signing progress + the assurance level being asked for.
+    // payload.kind_payload.required_assurance_level: "integrity_proof" | "advanced" | "qualified"
+  },
+  onComplete: (outcome) => {
+    // outcome.result: "signed" | "declined" | "countered"
+    // outcome.assuranceLevel: the level recorded (or null)
+    console.log("Signing outcome:", outcome.result);
+  },
+  onCancel: () => console.log("Signer dismissed the flow"),
+  onError: (error) => console.error("Error:", error),
+});
+
+signing.destroy();
+```
+
+The `<overturo-decision token="...">` custom element embeds a signing decision with
+**identical markup** to consent and approval — the kind is inferred server-side from
+the token; never declare it on the element.
+
+### CDN / Script tag
+
+```html
+<div id="consent-container"></div>
+<script src="https://unpkg.com/@overturo/js/dist/overturo.global.js"></script>
+<script>
+  const overturo = new Overturo({ publishableKey: "pk_live_..." });
+
+  overturo.consent({
+    flowId: "flw_...",
+    container: "#consent-container",
+    onComplete: function (result) {
+      console.log("Consent token:", result.consentToken);
+    },
+  });
+</script>
+```
+
+## API Reference
+
+### `new Overturo(options)`
+
+Creates a new client instance.
+
+| Option           | Type     | Required | Description                                       |
+| ---------------- | -------- | -------- | ------------------------------------------------- |
+| `publishableKey` | `string` | Yes      | Your publishable key (`pk_live_...` or `pk_test_...`) |
+| `apiKey`         | `string` | No       | API key for server-side operations (`sk_live_...`)    |
+| `baseUrl`        | `string` | No       | API base URL (defaults to `https://overturo.com`) |
+
+### `overturo.consent(options): Promise<EmbedHandle>`
+
+High-level method that creates a session and embeds the consent flow in one call.
+
+| Option       | Type                            | Required | Description                                |
+| ------------ | ------------------------------- | -------- | ------------------------------------------ |
+| `flowId`     | `string`                        | Yes      | Flow ID (`flw_...`)                        |
+| `container`  | `string \| HTMLElement`         | Yes      | CSS selector or DOM element                |
+| `scope`      | `string`                        | No       | Requested OAuth scopes (space-separated)   |
+| `state`      | `string`                        | No       | CSRF protection token                      |
+| `nonce`      | `string`                        | No       | ID token replay protection                 |
+| `skipSteps`  | `string[]`                      | No       | Steps to skip                              |
+| `style`      | `EmbedStyle`                    | No       | Iframe style overrides                     |
+| `loading`    | `string \| HTMLElement`         | No       | Loading placeholder                        |
+| `onComplete` | `(result: ConsentResult) => void` | No     | Called when user completes consent          |
+| `onCancel`   | `() => void`                    | No       | Called when user cancels                    |
+| `onError`    | `(error: string) => void`       | No       | Called on error                             |
+| `onStep`     | `(step: string) => void`        | No       | Called on step navigation                   |
+| `onResize`   | `(height: number) => void`      | No       | Called on iframe resize                     |
+| `onReady`    | `() => void`                    | No       | Called when iframe is ready                 |
+
+Returns an `EmbedHandle` with `{ iframe, destroy() }`.
+
+### `overturo.createSession(params): Promise<Session>`
+
+Creates a consent session manually.
+
+```typescript
+const session = await overturo.createSession({
+  flowId: "flw_...",
+  deliveryMode: "embed", // "embed" | "popup" | "redirect"
+  scope: "openid profile",
+});
+```
+
+### `overturo.getSession(sessionToken): Promise<SessionStatus>`
+
+Retrieves the status of an existing session.
+
+```typescript
+const status = await overturo.getSession("ses_...");
+console.log(status.status, status.currentStep);
+```
+
+### `overturo.embed(options): EmbedHandle`
+
+Embeds a consent flow using an existing session token.
+
+```typescript
+const widget = overturo.embed({
+  sessionToken: "ses_...",
+  container: "#el",
+  onComplete: (result) => console.log(result.consentToken),
+});
+widget.destroy();
+```
+
+### `overturo.popup(options): PopupHandle`
+
+Opens a consent flow in a popup window.
+
+```typescript
+const popup = overturo.popup({
+  sessionToken: "ses_...",
+  onComplete: (result) => console.log(result.consentToken),
+  onCancel: () => console.log("Cancelled"),
+  width: 500,
+  height: 700,
+});
+popup.close();
+```
+
+### `overturo.redirect(options): void`
+
+Redirects to a consent flow (full-page navigation).
+
+```typescript
+overturo.redirect({
+  flowId: "flw_...",
+  redirectUri: "https://yourapp.com/callback",
+  state: "csrf_token",
+  scope: "openid profile email",
+});
+```
+
+### `overturo.exchange(params): Promise<ExchangeResult>`
+
+Exchanges a consent token for claims, attestations, credentials, and tokens. **Requires `apiKey`** — use this on your server.
+
+```typescript
+const result = await overturo.exchange({
+  sessionToken: "ses_...",
+  consentToken: "ct_...",
+});
+// result.claims, result.attestations, result.credentials
+// result.accessToken, result.idToken (if OAuth configured)
+```
+
+## The embedded consent field (`@overturo/js/field`)
+
+A separate, explicitly loaded entry (`import "@overturo/js/field"` or `<script src="https://overturo.com/sdk/v1/overturo-field.js">`) registers `<overturo-consent-field>`: an Overturo-rendered consent control placed inside your own form. Attach it with the core facade:
+
+```js
+import { Overturo } from "@overturo/js"
+import "@overturo/js/field"
+
+const overturo = new Overturo({ publishableKey: "pk_live_…" })
+overturo.forms.attach({ flowId: "flw_…", form: "#signup", field: "overturo-consent-field", subjectField: "#email" })
+```
+
+The element is form-associated (its `value` is the capture token once captured), emits `field:ready`, `field:state`, `field:complete` and `field:error` events, takes `flow`, `purposes`, `locale`, `theme` and `appearance` attributes, and never loads a font or fetches anything of its own. One field per flow per form.
+
+## Style Overrides
+
+The embed iframe accepts these style properties:
+
+| Property       | Default         | Description     |
+| -------------- | --------------- | --------------- |
+| `width`        | `"100%"`        | CSS width       |
+| `minHeight`    | `"400px"`       | CSS min-height  |
+| `maxHeight`    | `"none"`        | CSS max-height  |
+| `border`       | `"none"`        | CSS border      |
+| `borderRadius` | `"0"`           | CSS border-radius |
+| `background`   | `"transparent"` | CSS background  |
+
+## Error Handling
+
+```typescript
+import {
+  OverturoError,
+  OverturoApiError,
+  OverturoNetworkError,
+  OverturoValidationError,
+} from "@overturo/js";
+
+try {
+  await overturo.createSession({ flowId: "flw_invalid" });
+} catch (err) {
+  if (err instanceof OverturoApiError) {
+    console.error(`API error ${err.status}:`, err.message);
+  } else if (err instanceof OverturoNetworkError) {
+    console.error("Network error:", err.message);
+  } else if (err instanceof OverturoValidationError) {
+    console.error("Validation:", err.message);
+  }
+}
+```
+
+## Framework Examples
+
+### React
+
+```tsx
+import { useEffect, useRef } from "react";
+import { Overturo } from "@overturo/js";
+
+function ConsentFlow({ flowId }: { flowId: string }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const overturo = new Overturo({ publishableKey: "pk_live_..." });
+    let handle: Awaited<ReturnType<typeof overturo.consent>> | null = null;
+
+    overturo
+      .consent({
+        flowId,
+        container: containerRef.current!,
+        onComplete: (result) => console.log(result.consentToken),
+      })
+      .then((h) => (handle = h));
+
+    return () => handle?.destroy();
+  }, [flowId]);
+
+  return <div ref={containerRef} />;
+}
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+import { onMounted, onUnmounted, ref } from "vue";
+import { Overturo, type EmbedHandle } from "@overturo/js";
+
+const props = defineProps<{ flowId: string }>();
+const container = ref<HTMLDivElement>();
+let handle: EmbedHandle | null = null;
+
+onMounted(async () => {
+  const overturo = new Overturo({ publishableKey: "pk_live_..." });
+  handle = await overturo.consent({
+    flowId: props.flowId,
+    container: container.value!,
+    onComplete: (result) => console.log(result.consentToken),
+  });
+});
+
+onUnmounted(() => handle?.destroy());
+</script>
+
+<template>
+  <div ref="container" />
+</template>
+```
+
+### Vanilla JS
+
+```html
+<div id="consent"></div>
+<script type="module">
+  import { Overturo } from "@overturo/js";
+
+  const overturo = new Overturo({ publishableKey: "pk_live_..." });
+  const flow = await overturo.consent({
+    flowId: "flw_...",
+    container: "#consent",
+    onComplete: (result) => {
+      document.getElementById("consent").innerHTML =
+        "<p>Done! Token: " + result.consentToken + "</p>";
+    },
+  });
+</script>
+```
+
+## Browser Support
+
+ES2020+: Chrome 80+, Firefox 80+, Safari 14+, Edge 80+.
+
+## TypeScript
+
+All types are exported and available:
+
+```typescript
+import type {
+  OverturoOptions,
+  ConsentOptions,
+  ConsentResult,
+  EmbedHandle,
+  Session,
+  ExchangeResult,
+} from "@overturo/js";
+```
+
+## Contract and testing
+
+This client is written against Overturo's published OpenAPI document, kept at
+<https://github.com/overturo/openapi> and rendered at
+<https://overturo.com/developers/openapi>, where each operation lists the SDKs that reach it. When the client and the API disagree, the
+document is the authority; a change to it is a change to this client.
+
+The test suite stubs recorded operations from the shared API response corpus
+(<https://github.com/overturo/conformance>, `api_responses/`), vendored under
+`__tests__/fixtures/api_responses`. Each recording was made against the real API and checked against
+the published document before it was committed, so a passing suite means the
+client parses what the API actually sends — not what a test author remembered.
+Identifiers, timestamps and tokens in the recordings are placeholders
+(`<PREFIX_ID:1>`, `2026-01-01T00:00:00Z`, `<TOKEN>`); the corpus README documents the
+grammar.
+
+Run the suite with `npm test`. When you add a test for a recorded operation, stub it
+from the recording (`corpusResponse("Decisions_create")`) rather than writing the response by hand.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE). Copyright 2026 Overturo Geneva Association.
+
+## Authority records — use a backend SDK
+
+This package is the browser UI-flow SDK, and the authority record
+endpoints take server-side token scopes (`audit:verify`,
+`disclosures:write`) that do not belong in a browser. Client methods
+live in the backend SDKs — `@overturo/sdk` (`/receipts` subpath),
+`overturo` (Python, `overturo.receipts`), and the `overturo` gem
+(`delegate_ns.authorization_receipts` / `disclosure_receipts`) —
+and signed-record verification lives in `@overturo/verify`
+(`verifyRecord`).