@veilgroup/sdk-woro 0.1.1

package/README.md

@@ -0,0 +1,78 @@
+# WORO JavaScript SDK
+
+Use WORO from JavaScript or TypeScript applications to send a piece of data and let its intended user retrieve it once.
+
+## Install
+
+```sh
+npm install @veilgroup/sdk-woro
+# or
+pnpm add @veilgroup/sdk-woro
+```
+
+## Send and retrieve data
+
+```ts
+import { WoroClient } from '@veilgroup/sdk-woro';
+
+const woro = new WoroClient({ writeToken: process.env.WORO_WRITE_TOKEN });
+const { readToken } = await woro.writeSecret('one-time value');
+
+// Share the read token with the person or application that needs the data.
+const received = await woro.readSecret(readToken);
+console.log(new TextDecoder().decode(received.data));
+```
+
+Reading consumes the data. WORO deletes its stored copy as it is retrieved. A read token can be redeemed only once. Data that is not redeemed expires after 14 days.
+
+The SDK also accepts binary data as a `Uint8Array`, `ArrayBuffer`, or `Blob`. A string is encoded as UTF-8. To create a read token before data is ready, call `createEmptySlot()` and later fill it once with `fillSecret(readToken, data)`.
+
+## Compression and encryption
+
+The SDK compresses data locally when compression makes the request smaller. The receiving application using this SDK restores the original data.
+
+Encryption is optional. Provide the same 32-byte key when writing and reading:
+
+```ts
+const key = crypto.getRandomValues(new Uint8Array(32));
+const { readToken } = await woro.writeSecret(file, {
+  encryptionKey: key,
+  contentType: 'application/octet-stream',
+});
+
+// Share the read token and encryption key through separate channels.
+const received = await woro.readSecret(readToken, { encryptionKey: key });
+```
+
+The SDK uses the key in your application and sends encrypted data to WORO. Share the key separately from the read token. Anyone who has both can decrypt the data. Keep keys out of URLs and logs. If retrieval succeeds but decryption fails, the SDK error includes the original encrypted bytes so they can be recovered with the correct key; the read token has still been consumed.
+
+The SDK's original and transformed request bodies must each fit WORO's 1 MiB request limit. The SDK also limits decompression to 1 MiB.
+
+## Account features
+
+Account features let you check your balance, manage write tokens, and inspect the status of a read token you created. Sign in with your WORO account username and password:
+
+```ts
+await woro.signIn(username, password);
+
+const balance = await woro.getAccountBalance();
+const writeTokens = await woro.listWriteTokens();
+const status = await woro.getSecretStatus(readToken);
+
+await woro.signOut();
+```
+
+Account features require the WORO account sign-in settings to be configured for your application. The SDK keeps the sign-in session in memory; `signOut()` clears it. The current sign-in flow does not support multi-factor authentication or forced password-reset challenges.
+
+## Credits and limits
+
+- Each call to `writeSecret()` or `createEmptySlot()` consumes one credit and starts the 14-day expiry period.
+- Filling an empty slot does not consume another credit.
+- Reading or deleting data does not refund the credit.
+- A request body can be up to 1 MiB after compression and optional encryption.
+
+API errors are reported as `WoroApiError`; sign-in errors as `WoroAuthError`; and payload processing errors as `WoroPayloadError`.
+
+## Licence
+
+This package is published as `UNLICENSED`. Downloading it does not grant general permission to use, modify, or redistribute it. Contact [support@veilgroup.au](mailto:support@veilgroup.au) to discuss permission.

package/dist/client.d.ts

@@ -0,0 +1,95 @@
+import { type PayloadOptions, type WoroInput } from './payload.js';
+export declare const WORO_PRODUCTION_URL = "https://woro.veilgroup.au";
+export interface CognitoConfig {
+    region: string;
+    userPoolId: string;
+    appClientId: string;
+}
+export interface WoroClientOptions {
+    baseUrl?: string;
+    writeToken?: string;
+    idToken?: string;
+    cognito?: CognitoConfig;
+    fetch?: typeof fetch;
+}
+export interface WriteOptions extends PayloadOptions {
+    writeToken?: string;
+}
+export interface ReadOptions {
+    encryptionKey?: Uint8Array;
+}
+export interface CreatedSecret {
+    readToken: string;
+    expiresAt: string;
+}
+export interface ReadSecret {
+    data: Uint8Array;
+    contentType: string;
+}
+export interface SecretStatus {
+    state: string | null;
+    createdAt: string | null;
+    expiresAt: string | null;
+    uploadedAt: string | null;
+    redeemedAt: string | null;
+    deletedAt: string | null;
+}
+export interface AccountOverview {
+    id: string;
+    email?: string;
+    status?: string;
+    createdAt?: string;
+    credits: number;
+    [key: string]: unknown;
+}
+export interface AccountBalance {
+    credits: number;
+    [key: string]: unknown;
+}
+export interface WriteTokenRecord {
+    id: string;
+    label?: string;
+    createdAt?: string;
+    active?: boolean;
+    [key: string]: unknown;
+}
+export interface CreatedWriteToken {
+    id: string;
+    token: string;
+    label?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+export declare class WoroClient {
+    readonly baseUrl: string;
+    private readonly fetcher;
+    private readonly cognito;
+    private writeToken;
+    private idToken;
+    private idTokenExpiresAt;
+    constructor(options?: WoroClientOptions);
+    setWriteToken(token: string | undefined): void;
+    setIdToken(token: string | undefined, expiresInSeconds?: number): void;
+    signOut(): void;
+    signIn(username: string, password: string): Promise<{
+        idToken: string;
+        expiresIn: number;
+    }>;
+    writeSecret(input: WoroInput, options?: WriteOptions): Promise<CreatedSecret>;
+    createEmptySlot(writeToken?: string): Promise<CreatedSecret>;
+    fillSecret(readToken: string, input: WoroInput, options?: PayloadOptions): Promise<void>;
+    readSecret(readToken: string, options?: ReadOptions): Promise<ReadSecret>;
+    deleteSecret(readToken: string): Promise<void>;
+    getSecretStatus(readToken: string): Promise<SecretStatus>;
+    getAccount(): Promise<AccountOverview>;
+    getAccountBalance(): Promise<AccountBalance>;
+    listWriteTokens(): Promise<WriteTokenRecord[]>;
+    createWriteToken(label: string): Promise<CreatedWriteToken>;
+    revokeWriteToken(tokenId: string): Promise<void>;
+    checkWriteToken(writeToken?: string): Promise<string | null>;
+    private getWriteToken;
+    private authorizationHeaders;
+    private assertPayloadSize;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+export declare class WoroApiError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+export declare class WoroAuthError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+export declare class WoroPayloadError extends Error {
+    readonly rawPayload?: Uint8Array | undefined;
+    constructor(message: string, rawPayload?: Uint8Array | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAa,SAAQ,KAAK;aAEnB,MAAM,EAAE,MAAM;aAEd,IAAI,CAAC,EAAE,MAAM;gBAFb,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED,qBAAa,aAAc,SAAQ,KAAK;aACO,IAAI,CAAC,EAAE,MAAM;gBAA9C,OAAO,EAAE,MAAM,EAAkB,IAAI,CAAC,EAAE,MAAM,YAAA;CAI3D;AAED,qBAAa,gBAAiB,SAAQ,KAAK;aACI,UAAU,CAAC,EAAE,UAAU;gBAAxD,OAAO,EAAE,MAAM,EAAkB,UAAU,CAAC,EAAE,UAAU,YAAA;CAIrE"}