@getvouch/sdk 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# Vouch SDK
+
+This is the Vouch SDK, a TypeScript library for interacting with vouch. Currently it allows you to generate a link to start the web proof flow.
+
+## Installation
+
+To install the Vouch SDK, you can use npm or other package managers.
+
+```bash
+npm install @vouch/vouch-sdk
+yarn add @vouch/vouch-sdk
+pnpm add @vouch/vouch-sdk
+bun add @vouch/vouch-sdk
+```
+
+## Usage
+
+Create vouch instance:
+
+```typescript
+import { Vouch } from "@vouch/vouch-sdk";
+const vouch = new Vouch();
+```
+
+You may provide a configuration object with a set of optional parameters:
+
+```typescript
+import { Vouch } from "@vouch/vouch-sdk";
+const vouch = new Vouch({
+  vouchHost: "https://app.getvouch.io", // The base URL for the Vouch API. Can be a string or an URL object. Defaults to "https://app.getvouch.io".
+});
+```
+
+### Get vouch start URL
+
+[Generate a link to start the Vouch flow](https://docs.getvouch.io/getting-started/first-steps#redirect-user-to-vouch).
+
+```typescript
+const url = vouch.getStartUrl({
+  requestId, // Optional. If not provided, a new request ID will be generated.
+  datasourceId: "93826be6-6c7d-495a-9859-de5a1d17f30b", // Datasource ID. Here we use example.com data source. Must be a UUIDv4.
+  customerId: "1be03be8-5014-413c-835a-feddf4020da2", // Your unique customer ID.
+  redirectBackUrl: `https://docs.getvouch.io/getting-started/first-steps?requestId=${requestId}`, // Return destination.
+  webhookUrl: `https://docs.getvouch.io/api/web-proof/${requestId}`, // (Optional) Proof delivery endpoint.
+});
+```

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./lib/vouch";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./lib/vouch";

package/dist/lib/vouch.d.ts

@@ -0,0 +1,16 @@
+export interface Config {
+    vouchHost?: string | URL;
+}
+export interface VouchUrlParams {
+    datasourceId: string;
+    redirectBackUrl: string;
+    customerId?: string;
+    requestId?: string;
+    inputs?: string;
+    webhookUrl?: string;
+}
+export declare class Vouch {
+    host: URL;
+    constructor({ vouchHost }?: Config);
+    getStartUrl({ customerId, datasourceId, requestId, redirectBackUrl, inputs, webhookUrl, }: VouchUrlParams): URL;
+}

package/dist/lib/vouch.js

@@ -0,0 +1,28 @@
+import { validatedHost } from "@/utils/validated-host";
+import { validatedUuidV4 } from "@/utils/validated-uuid";
+const DEFAULT_VOUCH_HOST = "https://app.getvouch.io";
+const DEFAULT_CUSTOMER_ID = "1be03be8-5014-413c-835a-feddf4020da2";
+export class Vouch {
+    constructor({ vouchHost = DEFAULT_VOUCH_HOST } = {}) {
+        this.host = validatedHost(vouchHost);
+    }
+    getStartUrl({ customerId, datasourceId, requestId, redirectBackUrl, inputs, webhookUrl, }) {
+        const params = new URLSearchParams({
+            requestId: requestId
+                ? validatedUuidV4(requestId, "requestId")
+                : crypto.randomUUID(),
+            customerId: customerId
+                ? validatedUuidV4(customerId, "customerId")
+                : DEFAULT_CUSTOMER_ID,
+            datasourceId: validatedUuidV4(datasourceId, "datasourceId"),
+            redirectBackUrl,
+        });
+        if (inputs) {
+            params.set("inputs", inputs);
+        }
+        if (webhookUrl) {
+            params.set("webhookUrl", webhookUrl);
+        }
+        return new URL(`/start?${params.toString()}`, this.host);
+    }
+}

package/dist/lib/vouch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/vouch.test.js

@@ -0,0 +1,79 @@
+import { Vouch } from "./vouch";
+import { beforeEach, expect } from "vitest";
+import { validatedUuidV4 } from "@/utils/validated-uuid";
+describe("Vouch SDK", () => {
+    it("correctly sets default vouch host", () => {
+        const vouch = new Vouch();
+        expect(vouch.host).toStrictEqual(new URL("https://app.getvouch.io"));
+    });
+    describe("getVouchUrl", () => {
+        let vouch;
+        beforeEach(() => {
+            vouch = new Vouch();
+        });
+        it("constructs correct URL", () => {
+            const params = {
+                requestId: crypto.randomUUID(),
+                datasourceId: crypto.randomUUID(),
+                customerId: crypto.randomUUID(),
+                redirectBackUrl: "https://example.com/redirect",
+            };
+            const url = vouch.getStartUrl(params);
+            expect(url.toString()).toBe(`https://app.getvouch.io/start?requestId=${params.requestId}&customerId=${params.customerId}&datasourceId=${params.datasourceId}&redirectBackUrl=${encodeURIComponent(params.redirectBackUrl)}`);
+        });
+        it("adds inputs", () => {
+            const params = {
+                requestId: crypto.randomUUID(),
+                datasourceId: crypto.randomUUID(),
+                customerId: crypto.randomUUID(),
+                redirectBackUrl: "https://example.com/redirect",
+                inputs: "eyJrZXkiOiAidmFsdWUifQ",
+            };
+            const url = vouch.getStartUrl(params);
+            expect(url.toString()).toBe(`https://app.getvouch.io/start?requestId=${params.requestId}&customerId=${params.customerId}&datasourceId=${params.datasourceId}&redirectBackUrl=${encodeURIComponent(params.redirectBackUrl)}&inputs=${params.inputs}`);
+        });
+        it("adds webhookUrl", () => {
+            const params = {
+                requestId: crypto.randomUUID(),
+                datasourceId: crypto.randomUUID(),
+                customerId: crypto.randomUUID(),
+                redirectBackUrl: "https://example.com/redirect",
+                webhookUrl: "https://example.com/webhook",
+            };
+            const url = vouch.getStartUrl(params);
+            expect(url.toString()).toBe(`https://app.getvouch.io/start?requestId=${params.requestId}&customerId=${params.customerId}&datasourceId=${params.datasourceId}&redirectBackUrl=${encodeURIComponent(params.redirectBackUrl)}&webhookUrl=${encodeURIComponent(params.webhookUrl)}`);
+        });
+        it("generates requestId", () => {
+            var _a;
+            const params = {
+                datasourceId: crypto.randomUUID(),
+                customerId: crypto.randomUUID(),
+                redirectBackUrl: "https://example.com/redirect",
+            };
+            const url = vouch.getStartUrl(params);
+            const generatedRequestId = (_a = url.searchParams.get("requestId")) !== null && _a !== void 0 ? _a : "";
+            expect(() => validatedUuidV4(generatedRequestId)).not.toThrow();
+        });
+        it("sets default customerId", () => {
+            const params = {
+                requestId: crypto.randomUUID(),
+                datasourceId: crypto.randomUUID(),
+                redirectBackUrl: "https://example.com/redirect",
+            };
+            const url = vouch.getStartUrl(params);
+            expect(url.searchParams.get("customerId")).toBe("1be03be8-5014-413c-835a-feddf4020da2");
+        });
+        it("validates UUIDs", () => {
+            const params = {
+                requestId: crypto.randomUUID(),
+                datasourceId: crypto.randomUUID(),
+                customerId: crypto.randomUUID(),
+                redirectBackUrl: "https://example.com/redirect",
+            };
+            const keys = ["requestId", "datasourceId", "customerId"];
+            keys.forEach((key) => {
+                expect(() => vouch.getStartUrl(Object.assign(Object.assign({}, params), { [key]: "invalid-uuid" }))).toThrow(`Invalid UUIDv4 for ${key}: invalid-uuid`);
+            });
+        });
+    });
+});

package/dist/utils/validated-host.d.ts

@@ -0,0 +1 @@
+export declare function validatedHost(url: string | URL): URL;

package/dist/utils/validated-host.js

@@ -0,0 +1,18 @@
+export function validatedHost(url) {
+    const parsedUrl = parseUrl(url);
+    if (!/^https?:$/.exec(parsedUrl.protocol)) {
+        throw new Error(`Invalid vouch host: ${url.toString()}. Only HTTP and HTTPS protocols are allowed.`);
+    }
+    if (parsedUrl.pathname !== "/" || parsedUrl.search || parsedUrl.hash) {
+        throw new Error(`Invalid vouch host: ${url.toString()}. Only root URLs are allowed as vouch host.`);
+    }
+    return parsedUrl;
+}
+function parseUrl(url) {
+    try {
+        return new URL(url);
+    }
+    catch (_a) {
+        throw new Error(`Invalid URL: ${url.toString()}`);
+    }
+}

package/dist/utils/validated-host.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/validated-host.test.js

@@ -0,0 +1,28 @@
+import { validatedHost } from "./validated-host";
+describe("Validate vouch host", () => {
+    it("should validate a valid vouch host URL", () => {
+        const validUrls = [
+            "https://vouch.example.com",
+            "https://vouch.example.com/",
+            "http://localhost:3000",
+            "http://127.0.0.1",
+            "http://127.0.0.1:3000",
+        ];
+        validUrls.forEach((url) => {
+            expect(() => validatedHost(url)).not.toThrow();
+        });
+    });
+    it("should throw an error for invalid vouch host URLs", () => {
+        const invalidUrls = [
+            "https://vouch.example.com/some/path",
+            "https://vouch.example.com?query=param",
+            "https://vouch.example.com#fragment",
+            "https://vouch.example.com/some/path?query=param#fragment",
+            "invalid-url",
+            "localhost:3000",
+        ];
+        invalidUrls.forEach((url) => {
+            expect(() => validatedHost(url)).toThrow();
+        });
+    });
+});

package/dist/utils/validated-uuid.d.ts

@@ -0,0 +1 @@
+export declare function validatedUuidV4(uuid: string, tag?: string): string;

package/dist/utils/validated-uuid.js

@@ -0,0 +1,7 @@
+export function validatedUuidV4(uuid, tag) {
+    const uuidv4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    if (!uuidv4Regex.test(uuid)) {
+        throw new Error(`Invalid UUIDv4${tag ? ` for ${tag}` : ""}: ${uuid}`);
+    }
+    return uuid.toLowerCase();
+}

package/dist/utils/validated-uuid.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/validated-uuid.test.js

@@ -0,0 +1,31 @@
+import { validatedUuidV4 } from "./validated-uuid";
+describe("Validate UUIDv4", () => {
+    it("passes for correct UUIDs", () => {
+        const exampleUuids = [
+            "f1df320a-774e-4061-ac7c-a0941d34a4fc",
+            "618379a9-7331-4556-b289-8039d1066aee",
+            "304875b0-becc-4ad6-a958-13867b03928c",
+            "4248b872-79b6-4e0d-a315-36b9579cae8c",
+        ];
+        exampleUuids.forEach((uuid) => {
+            expect(() => validatedUuidV4(uuid)).not.toThrow();
+        });
+    });
+    it("converts to lowercase", () => {
+        const uuid = crypto.randomUUID().toUpperCase();
+        expect(validatedUuidV4(uuid)).toBe(uuid.toLowerCase());
+    });
+    it("throws for incorrect UUIDs", () => {
+        const invalidUuids = [
+            "definitely not a uuid",
+            "12345678-1234-1234-1234-123456789012", // not a v4 UUID
+            "123e4567-e89b-12d3-a456-426614174000", // not a v4 UUID
+            "g23e4567-e89b-12d3-a456-426614174000", // invalid character
+            "123e4567-e89b-12d3-a456-42661417400", // too short
+            "123e4567-e89b-12d3-a456-4266141740000", // too long
+        ];
+        invalidUuids.forEach((uuid) => {
+            expect(() => validatedUuidV4(uuid)).toThrow();
+        });
+    });
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@getvouch/sdk",
+  "author": "Vouch",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vlayer-xyz/vouch.git#main"
+  },
+  "private": false,
+  "version": "0.1.0",
+  "description": "Vouch SDK",
+  "keywords": [
+    "webproof",
+    "sdk",
+    "vouch"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src && tsc --noEmit",
+    "lint:fix": "eslint src --fix && tsc --noEmit",
+    "format": "prettier --check .",
+    "format:fix": "prettier --write ."
+  },
+  "devDependencies": {
+    "eslint": "^9.24.0",
+    "eslint-config-prettier": "^10.1.1",
+    "eslint-plugin-prettier": "^5.2.6",
+    "prettier": "^3.5.3",
+    "typescript": "^5",
+    "typescript-eslint": "^8.30.1",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.3"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ES2017",
+    "types": ["vitest/globals"],
+    "moduleDetection": "force",
+    "moduleResolution": "node",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "allowJs": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules"]
+}