@paper19/gcforms-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gcforms-client contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# gcforms-client
+
+> [!IMPORTANT]
+> This is an unofficial, community-maintained client. It is not a Government of Canada project and is not affiliated with, maintained, or endorsed by the GC Forms team or the Canadian Digital Service.
+
+TypeScript client for the [GC Forms](https://articles.alpha.canada.ca/forms-formulaires/) (Government of Canada Forms) API. Handles OAuth2 JWT-bearer authentication against the GC Forms identity provider, retrieval and decryption of form submissions (RSA-OAEP + AES-256-GCM), integrity verification, attachment downloads, and confirmation — with built-in retries and typed errors.
+
+Requires Node.js 20 or later. ESM-only.
+
+## Install
+
+```sh
+npm install @paper19/gcforms-client
+```
+
+## Quick start
+
+Generate an API key for your form in GC Forms under **Settings → API integration**. This downloads a `<formId>_private_api_key.json` file — it is the only configuration the client needs.
+
+```ts
+import { readFile } from "node:fs/promises";
+import { GcFormsClient, gcFormsCredentialsSchema } from "@paper19/gcforms-client";
+
+const credentials = gcFormsCredentialsSchema.parse(
+  JSON.parse(await readFile("./<formId>_private_api_key.json", "utf8")),
+);
+
+const client = new GcFormsClient({ credentials });
+
+// Up to the 100 oldest submissions still in "New" status.
+const newSubmissions = await client.getNewSubmissions();
+
+for (const { name } of newSubmissions) {
+  // Fetches, decrypts and integrity-checks the submission.
+  const submission = await client.getSubmission(name);
+  const answers = JSON.parse(submission.answers);
+
+  // Attachment download links are only valid for ~10 seconds after
+  // retrieval — download immediately, before doing anything else.
+  for (const attachment of submission.attachments ?? []) {
+    if (attachment.isPotentiallyMalicious) continue; // flagged by GC Forms scanning
+    const bytes = await client.downloadAttachment(attachment);
+    // ...persist bytes...
+  }
+
+  // ...persist answers...
+
+  // Only confirm once everything is safely stored: confirmed submissions
+  // are deleted from GC Forms after 30 days.
+  await client.confirmSubmission(name, submission.confirmationCode);
+}
+```
+
+### Loading the key from Azure Key Vault
+
+```sh
+az keyvault secret set \
+  --vault-name <vault-name> \
+  --name gcforms-private-api-key \
+  --file <formId>_private_api_key.json
+```
+
+```ts
+import { DefaultAzureCredential } from "@azure/identity";
+import { SecretClient } from "@azure/keyvault-secrets";
+import { GcFormsClient, gcFormsCredentialsSchema } from "@paper19/gcforms-client";
+
+const vault = new SecretClient(
+  "https://<vault-name>.vault.azure.net",
+  new DefaultAzureCredential(),
+);
+
+const secret = await vault.getSecret("gcforms-private-api-key");
+if (!secret.value) {
+  throw new Error("Secret gcforms-private-api-key has no value");
+}
+
+const credentials = gcFormsCredentialsSchema.parse(JSON.parse(secret.value));
+const client = new GcFormsClient({ credentials });
+```
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `getFormTemplate()` | Form structure and question definitions (shape depends on the form). |
+| `getNewSubmissions()` | Up to the 100 oldest submissions in `New` status. |
+| `getSubmission(name)` | Fetches, decrypts and integrity-checks one submission. |
+| `getEncryptedSubmission(name)` | The raw encrypted envelope, if you want to decrypt later/elsewhere. |
+| `downloadAttachment(attachment)` | Downloads via the pre-signed link (valid ~10 s) → `ArrayBuffer`. |
+| `confirmSubmission(name, confirmationCode)` | Marks a submission as received. |
+| `reportProblem(name, problem)` | Flags a submission for GC Forms support review. |
+
+Standalone helpers `decryptFormSubmission(encrypted, credentials)` and `verifySubmissionIntegrity(answers, checksum)` are also exported, along with all zod schemas and inferred types (`formSubmissionSchema`, `FormSubmission`, …).
+
+## Configuration
+
+All fields except `credentials` are optional; the defaults point at the production GC Forms service.
+
+```ts
+new GcFormsClient({
+  credentials,                  // required — parsed <formId>_private_api_key.json
+  apiUrl,                       // default "https://api.forms-formulaires.alpha.canada.ca"
+  identityProviderUrl,          // default "https://auth.forms-formulaires.alpha.canada.ca"
+  projectIdentifier,            // default "284778202772022819" (GC Forms Zitadel project)
+  apiVersion,                   // default "v1"
+  timeoutMs,                    // default 10_000 — per request attempt
+  retry: {
+    maxAttempts,                // default 3 (total attempts; 1 disables retries)
+    baseDelayMs,                // default 250
+    maxDelayMs,                 // default 8_000
+    retryStatuses,              // default [429, 500, 502, 503, 504]
+  },
+});
+```
+
+Retries use exponential backoff with full jitter and honour `Retry-After` (capped at 30 s). Network errors and timeouts are retried; a `401` triggers a single re-authentication with a fresh token. Access tokens are cached per client instance and refreshed shortly before expiry.
+
+## Error handling
+
+Everything the package throws (other than zod validation errors on your own inputs) extends `GcFormsApiError`:
+
+```ts
+import { GcFormsApiError, GcFormsAuthError, GcFormsDecryptionError } from "@paper19/gcforms-client";
+
+try {
+  await client.getSubmission(name);
+} catch (error) {
+  if (error instanceof GcFormsAuthError) {
+    // token could not be obtained from the identity provider
+  } else if (error instanceof GcFormsDecryptionError) {
+    // decryption failed or the checksum did not match
+  } else if (error instanceof GcFormsApiError) {
+    console.error(error.status, error.responseBody, error.cause);
+  }
+}
+```
+
+## Security notes
+
+- The `key` in the private API key file is both the OAuth signing key and the submission decryption key — treat the whole file as a secret (do not commit it; load it from your secret store).
+- Check `attachment.isPotentiallyMalicious` before using attachments; it is set by GC Forms' malware scanning.
+- The MD5 `checksum` is the service's integrity check, not a security boundary — authenticity is provided by the AES-GCM auth tag.
+- Confirm a submission only after its answers and attachments are durably persisted; confirmed submissions are deleted from GC Forms after 30 days.
+
+## Development
+
+```sh
+npm install
+npm test           # vitest
+npm run typecheck  # tsc over src + tests
+npm run build      # emits dist/ (ESM + .d.ts)
+```
+
+Publishing: `npm version <patch|minor|major> && npm publish` (the `prepack` script builds `dist/` automatically).

package/dist/auth.d.ts

@@ -0,0 +1,27 @@
+import { type RetryOptions } from "./retry.js";
+import type { GcFormsCredentials } from "./types.js";
+export type GcFormsAuthConfig = {
+    identityProviderUrl: string;
+    projectIdentifier: string;
+    credentials: GcFormsCredentials;
+    timeoutMs: number;
+    retry: RetryOptions;
+};
+/** RS256-signed OAuth JWT-bearer assertion, as required by the GC Forms IdP (Zitadel). */
+export declare function signJwtAssertion({ identityProviderUrl, credentials, }: Pick<GcFormsAuthConfig, "identityProviderUrl" | "credentials">): string;
+/**
+ * Fetches and caches bearer tokens for the GC Forms API. Tokens are reused
+ * until shortly before expiry (they are valid for 30 minutes), and
+ * concurrent refreshes are coalesced into a single token request.
+ */
+export declare class TokenProvider {
+    private readonly config;
+    private cached;
+    private inflight;
+    constructor(config: GcFormsAuthConfig);
+    getAccessToken(): Promise<string>;
+    /** Drops the cached token so the next call fetches a fresh one. */
+    invalidate(): void;
+    private fetchToken;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAWrD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,kBAAkB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,YAAY,CAAC;CACrB,CAAC;AAEF,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,EAC/B,mBAAmB,EACnB,WAAW,GACZ,EAAE,IAAI,CAAC,iBAAiB,EAAE,qBAAqB,GAAG,aAAa,CAAC,GAAG,MAAM,CAwBzE;AAQD;;;;GAIG;AACH,qBAAa,aAAa;IAIL,OAAO,CAAC,QAAQ,CAAC,MAAM;IAH1C,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,QAAQ,CAA8B;gBAEV,MAAM,EAAE,iBAAiB;IAEhD,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAc9C,mEAAmE;IAC5D,UAAU,IAAI,IAAI;YAIX,UAAU;CAwDzB"}

package/dist/auth.js

@@ -0,0 +1,94 @@
+import { createPrivateKey, sign } from "node:crypto";
+import { z } from "zod";
+import { GcFormsAuthError } from "./errors.js";
+import { fetchWithRetry } from "./retry.js";
+const ASSERTION_LIFETIME_SECONDS = 60;
+const TOKEN_REFRESH_MARGIN_MS = 60_000;
+const DEFAULT_TOKEN_LIFETIME_SECONDS = 30 * 60;
+const tokenResponseSchema = z.object({
+    access_token: z.string().min(1),
+    expires_in: z.number().default(DEFAULT_TOKEN_LIFETIME_SECONDS),
+});
+/** RS256-signed OAuth JWT-bearer assertion, as required by the GC Forms IdP (Zitadel). */
+export function signJwtAssertion({ identityProviderUrl, credentials, }) {
+    const issuedAt = Math.floor(Date.now() / 1000);
+    const header = base64UrlJson({
+        alg: "RS256",
+        typ: "JWT",
+        kid: credentials.keyId,
+    });
+    const payload = base64UrlJson({
+        iss: credentials.userId,
+        sub: credentials.userId,
+        aud: identityProviderUrl,
+        iat: issuedAt,
+        exp: issuedAt + ASSERTION_LIFETIME_SECONDS,
+    });
+    const signingInput = `${header}.${payload}`;
+    const signature = sign("sha256", Buffer.from(signingInput), createPrivateKey(credentials.key)).toString("base64url");
+    return `${signingInput}.${signature}`;
+}
+function base64UrlJson(value) {
+    return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+/**
+ * Fetches and caches bearer tokens for the GC Forms API. Tokens are reused
+ * until shortly before expiry (they are valid for 30 minutes), and
+ * concurrent refreshes are coalesced into a single token request.
+ */
+export class TokenProvider {
+    config;
+    cached;
+    inflight;
+    constructor(config) {
+        this.config = config;
+    }
+    async getAccessToken() {
+        if (this.cached &&
+            this.cached.expiresAt - TOKEN_REFRESH_MARGIN_MS > Date.now()) {
+            return this.cached.value;
+        }
+        this.inflight ??= this.fetchToken().finally(() => {
+            this.inflight = undefined;
+        });
+        return this.inflight;
+    }
+    /** Drops the cached token so the next call fetches a fresh one. */
+    invalidate() {
+        this.cached = undefined;
+    }
+    async fetchToken() {
+        let response;
+        try {
+            response = await fetchWithRetry(`${this.config.identityProviderUrl}/oauth/v2/token`, () => ({
+                method: "POST",
+                body: new URLSearchParams({
+                    grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+                    assertion: signJwtAssertion(this.config),
+                    scope: `openid profile urn:zitadel:iam:org:project:id:${this.config.projectIdentifier}:aud`,
+                }),
+            }), this.config.timeoutMs, this.config.retry);
+        }
+        catch (error) {
+            throw new GcFormsAuthError("Failed to obtain GC Forms access token", undefined, undefined, { cause: error });
+        }
+        if (!response.ok) {
+            const responseBody = await response.text().catch(() => undefined);
+            throw new GcFormsAuthError(`Failed to obtain GC Forms access token (HTTP ${response.status})`, response.status, responseBody);
+        }
+        let access_token;
+        let expires_in;
+        try {
+            ({ access_token, expires_in } = tokenResponseSchema.parse(await response.json()));
+        }
+        catch (error) {
+            throw new GcFormsAuthError("GC Forms identity provider returned a malformed token response", undefined, undefined, { cause: error });
+        }
+        this.cached = {
+            value: access_token,
+            expiresAt: Date.now() + expires_in * 1000,
+        };
+        return access_token;
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+import { type RetryOptions } from "./retry.js";
+import { type Attachment, type EncryptedFormSubmission, type FormSubmission, type FormSubmissionProblem, type NewFormSubmission, type GcFormsCredentials } from "./types.js";
+export declare const DEFAULT_API_URL = "https://api.forms-formulaires.alpha.canada.ca";
+export declare const DEFAULT_IDENTITY_PROVIDER_URL = "https://auth.forms-formulaires.alpha.canada.ca";
+export declare const DEFAULT_PROJECT_IDENTIFIER = "284778202772022819";
+export type GcFormsClientConfig = {
+    /** Contents of the `<formId>_private_api_key.json` file from GC Forms. */
+    credentials: GcFormsCredentials;
+    /** @default DEFAULT_API_URL (the production GC Forms API) */
+    apiUrl?: string;
+    /** @default DEFAULT_IDENTITY_PROVIDER_URL (the production GC Forms IdP) */
+    identityProviderUrl?: string;
+    /** @default DEFAULT_PROJECT_IDENTIFIER (the production GC Forms Zitadel project) */
+    projectIdentifier?: string;
+    /** API version path segment. @default "v1" */
+    apiVersion?: string;
+    /** Per-attempt request timeout. @default 10_000 */
+    timeoutMs?: number;
+    retry?: RetryOptions;
+};
+export declare class GcFormsClient {
+    /** The form this client is bound to, taken from the private API key. */
+    readonly formId: string;
+    private readonly baseUrl;
+    private readonly credentials;
+    private readonly timeoutMs;
+    private readonly retry;
+    private readonly tokenProvider;
+    constructor(config: GcFormsClientConfig);
+    /** Form structure and question definitions; shape depends on the form. */
+    getFormTemplate(): Promise<Record<string, unknown>>;
+    /** Up to the 100 oldest submissions still in "New" status. */
+    getNewSubmissions(): Promise<NewFormSubmission[]>;
+    getEncryptedSubmission(submissionName: string): Promise<EncryptedFormSubmission>;
+    /**
+     * Retrieves, decrypts and integrity-checks a submission. Note that any
+     * `attachments[].downloadLink` is only valid for ~10 seconds — download
+     * promptly (see downloadAttachment) before confirming.
+     */
+    getSubmission(submissionName: string): Promise<FormSubmission>;
+    /**
+     * Marks a submission as received. Only confirm after its answers and
+     * attachments are safely persisted; confirmed submissions are deleted
+     * from GC Forms after 30 days.
+     */
+    confirmSubmission(submissionName: string, confirmationCode: string): Promise<void>;
+    /** Flags a submission for GC Forms support review. */
+    reportProblem(submissionName: string, problem: FormSubmissionProblem): Promise<void>;
+    /**
+     * Downloads an attachment via its pre-signed link (valid ~10 seconds).
+     * Callers should check `attachment.isPotentiallyMalicious` before use.
+     */
+    downloadAttachment(attachment: Attachment): Promise<ArrayBuffer>;
+    private request;
+    private send;
+}
+//# 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":"AAIA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAML,KAAK,UAAU,EACf,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,eAAe,kDAAkD,CAAC;AAC/E,eAAO,MAAM,6BAA6B,mDACQ,CAAC;AACnD,eAAO,MAAM,0BAA0B,uBAAuB,CAAC;AAK/D,MAAM,MAAM,mBAAmB,GAAG;IAChC,0EAA0E;IAC1E,WAAW,EAAE,kBAAkB,CAAC;IAChC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,qBAAa,aAAa;IACxB,wEAAwE;IACxE,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;gBAE3B,MAAM,EAAE,mBAAmB;IAqB9C,0EAA0E;IAC7D,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAShE,8DAA8D;IACjD,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAYjD,sBAAsB,CACjC,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,uBAAuB,CAAC;IAYnC;;;;OAIG;IACU,aAAa,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAyB3E;;;;OAIG;IACU,iBAAiB,CAC5B,cAAc,EAAE,MAAM,EACtB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,IAAI,CAAC;IAOhB,sDAAsD;IACzC,aAAa,CACxB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC;IAQhB;;;OAGG;IACU,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;YAgC/D,OAAO;YA2BP,IAAI;CA8BnB"}

package/dist/client.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { TokenProvider } from "./auth.js";
+import { decryptFormSubmission, verifySubmissionIntegrity } from "./crypto.js";
+import { GcFormsApiError, GcFormsDecryptionError } from "./errors.js";
+import { fetchWithRetry } from "./retry.js";
+import { encryptedFormSubmissionSchema, formSubmissionProblemSchema, formSubmissionSchema, newFormSubmissionSchema, gcFormsCredentialsSchema, } from "./types.js";
+export const DEFAULT_API_URL = "https://api.forms-formulaires.alpha.canada.ca";
+export const DEFAULT_IDENTITY_PROVIDER_URL = "https://auth.forms-formulaires.alpha.canada.ca";
+export const DEFAULT_PROJECT_IDENTIFIER = "284778202772022819";
+const DEFAULT_API_VERSION = "v1";
+const DEFAULT_TIMEOUT_MS = 10_000;
+export class GcFormsClient {
+    /** The form this client is bound to, taken from the private API key. */
+    formId;
+    baseUrl;
+    credentials;
+    timeoutMs;
+    retry;
+    tokenProvider;
+    constructor(config) {
+        this.credentials = gcFormsCredentialsSchema.parse(config.credentials);
+        this.formId = this.credentials.formId;
+        const apiUrl = trimTrailingSlashes(config.apiUrl ?? DEFAULT_API_URL);
+        const apiVersion = trimSlashes(config.apiVersion ?? DEFAULT_API_VERSION);
+        this.baseUrl = `${apiUrl}/${apiVersion}`;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.retry = config.retry ?? {};
+        this.tokenProvider = new TokenProvider({
+            identityProviderUrl: trimTrailingSlashes(config.identityProviderUrl ?? DEFAULT_IDENTITY_PROVIDER_URL),
+            projectIdentifier: config.projectIdentifier ?? DEFAULT_PROJECT_IDENTIFIER,
+            credentials: this.credentials,
+            timeoutMs: this.timeoutMs,
+            retry: this.retry,
+        });
+    }
+    /** Form structure and question definitions; shape depends on the form. */
+    async getFormTemplate() {
+        const response = await this.request("GET", `/forms/${this.formId}/template`);
+        return parseResponse(response, z.record(z.string(), z.unknown()), "form template");
+    }
+    /** Up to the 100 oldest submissions still in "New" status. */
+    async getNewSubmissions() {
+        const response = await this.request("GET", `/forms/${this.formId}/submission/new`);
+        return parseResponse(response, z.array(newFormSubmissionSchema), "new submissions");
+    }
+    async getEncryptedSubmission(submissionName) {
+        const response = await this.request("GET", `/forms/${this.formId}/submission/${encodeURIComponent(submissionName)}`);
+        return parseResponse(response, encryptedFormSubmissionSchema, `submission ${submissionName}`);
+    }
+    /**
+     * Retrieves, decrypts and integrity-checks a submission. Note that any
+     * `attachments[].downloadLink` is only valid for ~10 seconds — download
+     * promptly (see downloadAttachment) before confirming.
+     */
+    async getSubmission(submissionName) {
+        const encrypted = await this.getEncryptedSubmission(submissionName);
+        const decrypted = decryptFormSubmission(encrypted, this.credentials);
+        let submission;
+        try {
+            submission = formSubmissionSchema.parse(JSON.parse(decrypted));
+        }
+        catch (error) {
+            throw new GcFormsApiError(`GC Forms returned malformed decrypted data for submission ${submissionName}`, undefined, undefined, { cause: error });
+        }
+        if (!verifySubmissionIntegrity(submission.answers, submission.checksum)) {
+            throw new GcFormsDecryptionError(`Integrity check failed for submission ${submissionName}: answers do not match checksum`);
+        }
+        return submission;
+    }
+    /**
+     * Marks a submission as received. Only confirm after its answers and
+     * attachments are safely persisted; confirmed submissions are deleted
+     * from GC Forms after 30 days.
+     */
+    async confirmSubmission(submissionName, confirmationCode) {
+        await this.request("PUT", `/forms/${this.formId}/submission/${encodeURIComponent(submissionName)}/confirm/${encodeURIComponent(confirmationCode)}`);
+    }
+    /** Flags a submission for GC Forms support review. */
+    async reportProblem(submissionName, problem) {
+        await this.request("POST", `/forms/${this.formId}/submission/${encodeURIComponent(submissionName)}/problem`, formSubmissionProblemSchema.parse(problem));
+    }
+    /**
+     * Downloads an attachment via its pre-signed link (valid ~10 seconds).
+     * Callers should check `attachment.isPotentiallyMalicious` before use.
+     */
+    async downloadAttachment(attachment) {
+        let data;
+        let response;
+        try {
+            response = await fetchWithRetry(attachment.downloadLink, () => ({}), this.timeoutMs, this.retry, async (ok) => {
+                data = await ok.arrayBuffer();
+            });
+        }
+        catch (error) {
+            throw new GcFormsApiError(`Failed to download attachment '${attachment.name}'`, undefined, undefined, { cause: error });
+        }
+        if (!response.ok || data === undefined) {
+            throw new GcFormsApiError(`Failed to download attachment '${attachment.name}' (HTTP ${response.status})`, response.status);
+        }
+        return data;
+    }
+    async request(method, path, body) {
+        let response = await this.send(method, path, body);
+        // The cached token can be revoked server-side before its expiry; retry
+        // once with a freshly fetched token.
+        if (response.status === 401) {
+            await response.body?.cancel().catch(() => { });
+            this.tokenProvider.invalidate();
+            response = await this.send(method, path, body);
+        }
+        if (!response.ok) {
+            const responseBody = await response.text().catch(() => undefined);
+            throw new GcFormsApiError(`GC Forms request failed: ${method} ${path} (HTTP ${response.status})`, response.status, responseBody);
+        }
+        return response;
+    }
+    async send(method, path, body) {
+        const accessToken = await this.tokenProvider.getAccessToken();
+        try {
+            return await fetchWithRetry(`${this.baseUrl}${path}`, () => ({
+                method,
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    ...(body !== undefined && { "Content-Type": "application/json" }),
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            }), this.timeoutMs, this.retry);
+        }
+        catch (error) {
+            throw new GcFormsApiError(`GC Forms request failed: ${method} ${path}`, undefined, undefined, { cause: error });
+        }
+    }
+}
+/** Parses a successful response body, translating malformed server data into GcFormsApiError. */
+async function parseResponse(response, schema, description) {
+    try {
+        return schema.parse(await response.json());
+    }
+    catch (error) {
+        throw new GcFormsApiError(`GC Forms returned an unexpected response for ${description}`, undefined, undefined, { cause: error });
+    }
+}
+function trimTrailingSlashes(value) {
+    return value.replace(/\/+$/, "");
+}
+function trimSlashes(value) {
+    return value.replace(/^\/+|\/+$/g, "");
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/crypto.d.ts

@@ -0,0 +1,14 @@
+import type { EncryptedFormSubmission, GcFormsCredentials } from "./types.js";
+/**
+ * Decrypts a submission payload: the AES key, nonce and auth tag are each
+ * RSA-OAEP(SHA-256) encrypted with the form's key pair, and the responses
+ * themselves are AES-256-GCM encrypted. Returns the decrypted JSON string.
+ */
+export declare function decryptFormSubmission(encryptedSubmission: EncryptedFormSubmission, credentials: GcFormsCredentials): string;
+/**
+ * Verifies the MD5 checksum GC Forms computes over the `answers` string.
+ * MD5 is what the service uses; it is an integrity check, not a security
+ * boundary (authenticity is already covered by the GCM auth tag).
+ */
+export declare function verifySubmissionIntegrity(answers: string, checksum: string): boolean;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE9E;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,mBAAmB,EAAE,uBAAuB,EAC5C,WAAW,EAAE,kBAAkB,GAC9B,MAAM,CA+BR;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAET"}

package/dist/crypto.js

@@ -0,0 +1,36 @@
+import { createDecipheriv, createHash, privateDecrypt } from "node:crypto";
+import { GcFormsDecryptionError } from "./errors.js";
+/**
+ * Decrypts a submission payload: the AES key, nonce and auth tag are each
+ * RSA-OAEP(SHA-256) encrypted with the form's key pair, and the responses
+ * themselves are AES-256-GCM encrypted. Returns the decrypted JSON string.
+ */
+export function decryptFormSubmission(encryptedSubmission, credentials) {
+    try {
+        const privateKey = { key: credentials.key, oaepHash: "sha256" };
+        const key = privateDecrypt(privateKey, Buffer.from(encryptedSubmission.encryptedKey, "base64"));
+        const nonce = privateDecrypt(privateKey, Buffer.from(encryptedSubmission.encryptedNonce, "base64"));
+        const authTag = privateDecrypt(privateKey, Buffer.from(encryptedSubmission.encryptedAuthTag, "base64"));
+        const decipher = createDecipheriv("aes-256-gcm", key, nonce);
+        decipher.setAuthTag(authTag);
+        const decrypted = Buffer.concat([
+            decipher.update(Buffer.from(encryptedSubmission.encryptedResponses, "base64")),
+            decipher.final(),
+        ]);
+        return decrypted.toString("utf8");
+    }
+    catch (error) {
+        throw new GcFormsDecryptionError("Failed to decrypt form submission", {
+            cause: error,
+        });
+    }
+}
+/**
+ * Verifies the MD5 checksum GC Forms computes over the `answers` string.
+ * MD5 is what the service uses; it is an integrity check, not a security
+ * boundary (authenticity is already covered by the GCM auth tag).
+ */
+export function verifySubmissionIntegrity(answers, checksum) {
+    return createHash("md5").update(answers).digest("hex") === checksum;
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAGrD;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,mBAA4C,EAC5C,WAA+B;IAE/B,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;QAEhE,MAAM,GAAG,GAAG,cAAc,CACxB,UAAU,EACV,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,YAAY,EAAE,QAAQ,CAAC,CACxD,CAAC;QACF,MAAM,KAAK,GAAG,cAAc,CAC1B,UAAU,EACV,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,cAAc,EAAE,QAAQ,CAAC,CAC1D,CAAC;QACF,MAAM,OAAO,GAAG,cAAc,CAC5B,UAAU,EACV,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAC5D,CAAC;QAEF,MAAM,QAAQ,GAAG,gBAAgB,CAAC,aAAa,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7D,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAE7B,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;YAC9B,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;YAC9E,QAAQ,CAAC,KAAK,EAAE;SACjB,CAAC,CAAC;QAEH,OAAO,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,sBAAsB,CAAC,mCAAmC,EAAE;YACpE,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAe,EACf,QAAgB;IAEhB,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC;AACtE,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Base class for every error thrown by this package; `instanceof
+ * GcFormsApiError` catches them all.
+ */
+export declare class GcFormsApiError extends Error {
+    readonly status?: number | undefined;
+    readonly responseBody?: string | undefined;
+    constructor(message: string, status?: number | undefined, responseBody?: string | undefined, options?: ErrorOptions);
+}
+/** Failure to obtain an access token from the GC Forms identity provider. */
+export declare class GcFormsAuthError extends GcFormsApiError {
+    constructor(message: string, status?: number, responseBody?: string, options?: ErrorOptions);
+}
+/** Failure to decrypt a submission or verify its integrity checksum. */
+export declare class GcFormsDecryptionError extends GcFormsApiError {
+    constructor(message: string, options?: ErrorOptions);
+}
+//# 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;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,MAAM,CAAC,EAAE,MAAM;aACf,YAAY,CAAC,EAAE,MAAM;gBAFrC,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,YAAY,CAAC,EAAE,MAAM,YAAA,EACrC,OAAO,CAAC,EAAE,YAAY;CAKzB;AAED,6EAA6E;AAC7E,qBAAa,gBAAiB,SAAQ,eAAe;gBAEjD,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,YAAY;CAKzB;AAED,wEAAwE;AACxE,qBAAa,sBAAuB,SAAQ,eAAe;gBACtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAI3D"}

package/dist/errors.js

@@ -0,0 +1,29 @@
+/**
+ * Base class for every error thrown by this package; `instanceof
+ * GcFormsApiError` catches them all.
+ */
+export class GcFormsApiError extends Error {
+    status;
+    responseBody;
+    constructor(message, status, responseBody, options) {
+        super(message, options);
+        this.status = status;
+        this.responseBody = responseBody;
+        this.name = "GcFormsApiError";
+    }
+}
+/** Failure to obtain an access token from the GC Forms identity provider. */
+export class GcFormsAuthError extends GcFormsApiError {
+    constructor(message, status, responseBody, options) {
+        super(message, status, responseBody, options);
+        this.name = "GcFormsAuthError";
+    }
+}
+/** Failure to decrypt a submission or verify its integrity checksum. */
+export class GcFormsDecryptionError extends GcFormsApiError {
+    constructor(message, options) {
+        super(message, undefined, undefined, options);
+        this.name = "GcFormsDecryptionError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAGtB;IACA;IAHlB,YACE,OAAe,EACC,MAAe,EACf,YAAqB,EACrC,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAJR,WAAM,GAAN,MAAM,CAAS;QACf,iBAAY,GAAZ,YAAY,CAAS;QAIrC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,6EAA6E;AAC7E,MAAM,OAAO,gBAAiB,SAAQ,eAAe;IACnD,YACE,OAAe,EACf,MAAe,EACf,YAAqB,EACrB,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,OAAO,sBAAuB,SAAQ,eAAe;IACzD,YAAmB,OAAe,EAAE,OAAsB;QACxD,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { GcFormsClient, DEFAULT_API_URL, DEFAULT_IDENTITY_PROVIDER_URL, DEFAULT_PROJECT_IDENTIFIER, } from "./client.js";
+export type { GcFormsClientConfig } from "./client.js";
+export { GcFormsApiError, GcFormsAuthError, GcFormsDecryptionError, } from "./errors.js";
+export type { RetryOptions } from "./retry.js";
+export { decryptFormSubmission, verifySubmissionIntegrity } from "./crypto.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,eAAe,EACf,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC/E,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { GcFormsClient, DEFAULT_API_URL, DEFAULT_IDENTITY_PROVIDER_URL, DEFAULT_PROJECT_IDENTIFIER, } from "./client.js";
+export { GcFormsApiError, GcFormsAuthError, GcFormsDecryptionError, } from "./errors.js";
+export { decryptFormSubmission, verifySubmissionIntegrity } from "./crypto.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,eAAe,EACf,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC/E,cAAc,YAAY,CAAC"}

package/dist/retry.d.ts

@@ -0,0 +1,23 @@
+export type RetryOptions = {
+    /** Total number of attempts, including the first. Set to 1 to disable retries. */
+    maxAttempts?: number;
+    /** Base for the exponential backoff between attempts. */
+    baseDelayMs?: number;
+    /** Upper bound on the backoff between attempts. */
+    maxDelayMs?: number;
+    /** HTTP status codes that trigger a retry. */
+    retryStatuses?: number[];
+};
+/**
+ * fetch with a per-attempt timeout and exponential backoff (full jitter) on
+ * retryable statuses and network errors. `makeInit` is called once per
+ * attempt so time-sensitive request material (e.g. a signed JWT assertion)
+ * is rebuilt fresh. Returns the last response, retryable or not; throws only
+ * when the final attempt fails at the network level.
+ *
+ * `consumeBody`, when given, runs for each ok response inside the attempt,
+ * so the per-attempt timeout and retry policy cover the body download too —
+ * a body read aborted by the timeout retries like any network error.
+ */
+export declare function fetchWithRetry(url: string, makeInit: () => RequestInit, timeoutMs: number, { maxAttempts, baseDelayMs, maxDelayMs, retryStatuses, }?: RetryOptions, consumeBody?: (response: Response) => Promise<void>): Promise<Response>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG;IACzB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AAKF;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,WAAW,EAC3B,SAAS,EAAE,MAAM,EACjB,EACE,WAAe,EACf,WAAiB,EACjB,UAAkB,EAClB,aAAyC,GAC1C,GAAE,YAAiB,EACpB,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,GAClD,OAAO,CAAC,QAAQ,CAAC,CA6BnB"}

package/dist/retry.js

@@ -0,0 +1,60 @@
+/** Never wait longer than this between attempts, even if Retry-After asks for more. */
+const RETRY_AFTER_CAP_MS = 30_000;
+/**
+ * fetch with a per-attempt timeout and exponential backoff (full jitter) on
+ * retryable statuses and network errors. `makeInit` is called once per
+ * attempt so time-sensitive request material (e.g. a signed JWT assertion)
+ * is rebuilt fresh. Returns the last response, retryable or not; throws only
+ * when the final attempt fails at the network level.
+ *
+ * `consumeBody`, when given, runs for each ok response inside the attempt,
+ * so the per-attempt timeout and retry policy cover the body download too —
+ * a body read aborted by the timeout retries like any network error.
+ */
+export async function fetchWithRetry(url, makeInit, timeoutMs, { maxAttempts = 3, baseDelayMs = 250, maxDelayMs = 8_000, retryStatuses = [429, 500, 502, 503, 504], } = {}, consumeBody) {
+    const backoffDelayMs = (attempt) => Math.random() * Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+    for (let attempt = 0;; attempt++) {
+        const isLastAttempt = attempt >= maxAttempts - 1;
+        let response;
+        try {
+            response = await fetch(url, {
+                ...makeInit(),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (response.ok && consumeBody) {
+                await consumeBody(response);
+            }
+        }
+        catch (error) {
+            if (isLastAttempt)
+                throw error;
+            await sleep(backoffDelayMs(attempt));
+            continue;
+        }
+        if (isLastAttempt || !retryStatuses.includes(response.status)) {
+            return response;
+        }
+        await response.body?.cancel().catch(() => { });
+        await sleep(retryAfterMs(response) ?? backoffDelayMs(attempt));
+    }
+}
+function retryAfterMs(response) {
+    const header = response.headers.get("retry-after");
+    // Treat an empty value as absent: Number("") is 0, which would turn a
+    // buggy proxy's bare header into zero-delay retries with no backoff.
+    if (header === null || header.trim() === "")
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.min(seconds * 1000, RETRY_AFTER_CAP_MS);
+    }
+    const date = Date.parse(header);
+    if (!Number.isNaN(date)) {
+        return Math.min(Math.max(0, date - Date.now()), RETRY_AFTER_CAP_MS);
+    }
+    return undefined;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+/**
+ * Contents of the `<formId>_private_api_key.json` file generated from
+ * GC Forms under "Settings > API integration". `key` is a PEM-encoded
+ * RSA private key used both to sign the OAuth JWT assertion and to
+ * decrypt submissions.
+ */
+export declare const gcFormsCredentialsSchema: z.ZodObject<{
+    keyId: z.ZodString;
+    key: z.ZodString;
+    userId: z.ZodString;
+    formId: z.ZodString;
+}, z.core.$strip>;
+export type GcFormsCredentials = z.infer<typeof gcFormsCredentialsSchema>;
+export declare const newFormSubmissionSchema: z.ZodObject<{
+    name: z.ZodString;
+    createdAt: z.ZodNumber;
+}, z.core.$strip>;
+export type NewFormSubmission = z.infer<typeof newFormSubmissionSchema>;
+export declare const encryptedFormSubmissionSchema: z.ZodObject<{
+    encryptedKey: z.ZodString;
+    encryptedNonce: z.ZodString;
+    encryptedAuthTag: z.ZodString;
+    encryptedResponses: z.ZodString;
+}, z.core.$strip>;
+export type EncryptedFormSubmission = z.infer<typeof encryptedFormSubmissionSchema>;
+export declare const formSubmissionStatusSchema: z.ZodEnum<{
+    New: "New";
+    Downloaded: "Downloaded";
+    Confirmed: "Confirmed";
+    Problem: "Problem";
+}>;
+export type FormSubmissionStatus = z.infer<typeof formSubmissionStatusSchema>;
+export declare const attachmentSchema: z.ZodObject<{
+    name: z.ZodString;
+    downloadLink: z.ZodString;
+    isPotentiallyMalicious: z.ZodBoolean;
+}, z.core.$strip>;
+export type Attachment = z.infer<typeof attachmentSchema>;
+export declare const formSubmissionSchema: z.ZodObject<{
+    createdAt: z.ZodNumber;
+    status: z.ZodEnum<{
+        New: "New";
+        Downloaded: "Downloaded";
+        Confirmed: "Confirmed";
+        Problem: "Problem";
+    }>;
+    confirmationCode: z.ZodString;
+    answers: z.ZodString;
+    checksum: z.ZodString;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        downloadLink: z.ZodString;
+        isPotentiallyMalicious: z.ZodBoolean;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type FormSubmission = z.infer<typeof formSubmissionSchema>;
+export declare const formSubmissionProblemSchema: z.ZodObject<{
+    contactEmail: z.ZodEmail;
+    description: z.ZodString;
+    preferredLanguage: z.ZodEnum<{
+        en: "en";
+        fr: "fr";
+    }>;
+}, z.core.$strip>;
+export type FormSubmissionProblem = z.infer<typeof formSubmissionProblemSchema>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;iBAKnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,6BAA6B;;;;;iBAKxC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;EAKrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,gBAAgB;;;;iBAK3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;iBAQ/B,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,2BAA2B;;;;;;;iBAItC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+/**
+ * Contents of the `<formId>_private_api_key.json` file generated from
+ * GC Forms under "Settings > API integration". `key` is a PEM-encoded
+ * RSA private key used both to sign the OAuth JWT assertion and to
+ * decrypt submissions.
+ */
+export const gcFormsCredentialsSchema = z.object({
+    keyId: z.string().min(1),
+    key: z.string().min(1),
+    userId: z.string().min(1),
+    formId: z.string().min(1),
+});
+export const newFormSubmissionSchema = z.object({
+    name: z.string().min(1),
+    createdAt: z.number(),
+});
+export const encryptedFormSubmissionSchema = z.object({
+    encryptedKey: z.string().min(1),
+    encryptedNonce: z.string().min(1),
+    encryptedAuthTag: z.string().min(1),
+    encryptedResponses: z.string().min(1),
+});
+export const formSubmissionStatusSchema = z.enum([
+    "New",
+    "Downloaded",
+    "Confirmed",
+    "Problem",
+]);
+export const attachmentSchema = z.object({
+    name: z.string(),
+    /** Pre-signed URL, only valid for ~10 seconds after retrieval. */
+    downloadLink: z.string(),
+    isPotentiallyMalicious: z.boolean(),
+});
+export const formSubmissionSchema = z.object({
+    createdAt: z.number(),
+    status: formSubmissionStatusSchema,
+    confirmationCode: z.string(),
+    /** JSON string mapping question ids to answers; shape depends on the form template. */
+    answers: z.string(),
+    checksum: z.string(),
+    attachments: z.array(attachmentSchema).optional(),
+});
+export const formSubmissionProblemSchema = z.object({
+    contactEmail: z.email(),
+    description: z.string().min(10),
+    preferredLanguage: z.enum(["en", "fr"]),
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC1B,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IACpD,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACtC,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,IAAI,CAAC;IAC/C,KAAK;IACL,YAAY;IACZ,WAAW;IACX,SAAS;CACV,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,kEAAkE;IAClE,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,sBAAsB,EAAE,CAAC,CAAC,OAAO,EAAE;CACpC,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,0BAA0B;IAClC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE;IAC5B,uFAAuF;IACvF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE;CAClD,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,YAAY,EAAE,CAAC,CAAC,KAAK,EAAE;IACvB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IAC/B,iBAAiB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;CACxC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@paper19/gcforms-client",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Unofficial TypeScript client for the Government of Canada Forms API (auth, submission decryption, retries)",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "gcforms",
+    "gc-forms",
+    "canada",
+    "forms",
+    "api-client"
+  ],
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5",
+    "vitest": "^3"
+  }
+}