Generate and validate a TypeScript Axios client from LibreSign OpenAPI

Start by validating the repository's openapi-full.json with the pinned OpenAPI Generator CLI, then generate typescript-axios into a disposable build/sdk-generation/typescript/ directory under a new tests/sdk-generation/ harness. Compare the 88 operationId values with the generated methods, and write focused type and Axios-transport tests for the four named operations. Done means a reproducible Go/No-Go report with the generation and compile results recorded, and no hand-edited generated code or OpenAPI changes.

Objective

Generate a real, typed TypeScript HTTP client for LibreSign's existing API, from the approved openapi-full.json, and establish whether OpenAPI Generator's typescript-axios output is suitable as the foundation of an official LibreSign SDK.

Deliver an executable, reproducible compatibility evaluation and Go/No-Go decision—not an npm package, not a frontend migration, and not a generic research report.

Inputs and required output

Input:

• openapi-full.json after the ten functional tags have been implemented in PHP controllers and regenerated.
• The exact LibreSign source revision and a pinned OpenAPI Generator version/configuration.

Expected generated output:

• TypeScript API classes/exports organized according to the ten approved functional tags.
• Typed API methods covering the full OpenAPI operation inventory, with request-parameter and response types.
• Typed models based on OpenAPI schemas.
• Axios-backed HTTP execution configurable by callers (base URL, Axios instance, authentication and headers).

The generated package is temporary validation output. It must be generated from the OpenAPI input and must not be manually corrected, committed as a permanent SDK or published.

Do not confuse this evaluation with LibreSign's existing openapi-typescript output: that tool generates type declarations currently used by the frontend, whereas this task evaluates typescript-axios for generating callable HTTP client code.

Implementation workflow

1. Pin tooling and establish a reproducible command

Set up a small isolated development/test harness, under a location consistent with the repository's conventions (for example tests/sdk-generation/), containing:

• A pinned OpenAPI Generator CLI version.
• The chosen typescript-axios configuration, starting by evaluating useSingleRequestParameter=true.
• A documented script or command that takes the repository's openapi-full.json and writes to a disposable directory such as build/sdk-generation/typescript/.
• Dependencies and a TypeScript compile command using pinned, mutually compatible versions.
• Focused compatibility tests and brief instructions to reproduce results.

A representative CLI invocation, not a substitute for pinning the actual tool version:

openapi-generator-cli validate -i openapi-full.json
openapi-generator-cli generate \
  -i openapi-full.json \
  -g typescript-axios \
  -o build/sdk-generation/typescript \
  --additional-properties=useSingleRequestParameter=true

Run validation rather than suppressing errors with --skip-validate-spec. If a generator limitation requires a change, explain the impact and record it as part of the evaluation, not as an unreviewed workaround.

2. Verify complete operation inventory and generated API grouping

Compare the input's 88 operationId values with the output's callable methods.

Check for:

• Missing or duplicate operations.
• Incorrectly generated parameter signatures.
• Grouping by the approved policies, identity, documents, requests, signing, appearance, verification, certificates, notifications and system tags.
• Name collisions or unusable exports.
• Correct handling of administration operations, without interpreting a tag as an authorization grant.

Record the actual generated class and method names. Do not assume a naming convention without testing the generator.

A method may exist in the generated output while still being unusable at runtime; distinguish method presence from compatible request serialization.

3. Compile and evaluate generated models

Compile generated TypeScript without editing generated source files.

Add small type-level acceptance checks using real contracts from openapi-full.json, including:

• EffectivePolicyValue (anyOf).
• NewFile.nodeId (oneOf).
• SignerDetail (allOf).
• Representative nullable/optional properties and enum fields.

Test that representative invalid types are rejected, not just that valid types compile. Treat unbounded any or incorrectly widened critical types as failures, not evidence of compatibility.

The generator's real support for these schema constructs must be determined empirically; do not assume that a successful compile guarantees model fidelity.

4. Execute generated calls through a controlled Axios transport

Use a small mocked Axios adapter or equivalent deterministic transport that inspects requests made by the generated client, not manually constructed example requests.

Test at least these four representative operations:

operationId	Expected behavior to prove
account-me	GET /ocs/v2.php/apps/libresign/api/v1/account/me, OCS header, injected authentication, typed OCS response envelope
policy-get-system	Correct URL/path parameter encoding for GET .../policies/system/{policyKey}; administration operation remains server-authorized
request_signature-request-signature	POST .../request-signature, JSON serialization, expected typed response
certificate_policy-get-certificate-policy	Non-OCS GET /index.php/apps/libresign/certificate-policy.pdf, preserving binary/download semantics where relevant

Also verify that a Nextcloud installation under https://example.test/nextcloud produces correct OCS and non-OCS paths, without missing or duplicated prefixes.

Test that callers can configure the Axios client without a hard dependency on @nextcloud/axios, while remaining compatible with a supplied Nextcloud Axios instance.

The OCS request path and required OCS-APIRequest header must be handled correctly. Check transport-level status/error behavior and the typed response envelope; do not assume the generated client automatically unwraps ocs.data.

Use synthetic fixtures; never commit tokens or real user data.

5. Document unsupported multipart-related operations

Current runtime controllers accept upload data from IRequest::getUploadedFile(), but some multipart request bodies are not completely reflected in generated OpenAPI.

Inspect, at minimum:

• account-upload-pfx.
• file-save.
• admin-signature-background-save.

Record whether the generated client exposes the necessary typed parameters and serializes them correctly. List missing fields/operations and the implications for an official SDK/frontend migration.

Do not edit OpenAPI JSON by hand, implement local extractor workarounds or modify PHP endpoints as part of this task.

6. Measure reproducibility and execution cost

Generate twice from the same commit/configuration and compare the generated source files (ignoring only explicitly documented nondeterministic metadata). Record:

• Source specification revision/hash.
• Generator and TypeScript/Axios versions and configuration.
• Exact commands run.
• Validation and compilation outcome.
• Results of each focused type and transport test.
• Generator/test runtime and repeatability.
• Identified limitations.

Keep the harness independently runnable. Do not introduce a new mandatory workflow or multiply existing PHP/Nextcloud test matrices solely for this evaluation. Any proposed recurring CI check requires measured benefit and runtime cost.

Deliverables

1. A reproducible, version-pinned command/script for generating and compiling the TypeScript client.
2. Focused automated tests for generated types, methods, URLs, headers, serialization and representative responses.
3. A concise compatibility report with complete operation inventory, unsupported features and measured cost.
4. A final Go/No-Go decision, with a clear handoff to the future SDK Generator implementation.

The generated TypeScript client itself remains disposable build output.

Definition of done

• The source is the full, classified OpenAPI contract at a named revision.
• The toolchain and settings are pinned and documented.
• Two generations from identical inputs produce equivalent source output.
• The compile result is recorded, without manual generated-code patches.
• All input operations are inventoried against generated callable methods; omissions or conflicts are explicitly reported.
• The functional tag grouping is verified.
• Representative oneOf, anyOf, allOf, nullable and enum types are evaluated with positive and negative type-level tests.
• The four specified representative operations are exercised through the generated Axios client where supported.
• OCS headers, customizable authentication, normal/subdirectory base URLs, non-OCS paths and response handling are examined.
• Multipart limitations and their consequences are documented.
• Duration and CI cost are reported.
• A defensible Go/No-Go decision with reproducible evidence is recorded.

Go means the generated output is sufficiently correct to plan official SDK generator infrastructure, with explicit mitigation requirements for documented limitations. It does not mean that the SDK is ready to publish.

No-Go is an acceptable outcome of this evaluation when a fundamental model, serialization or transport requirement cannot be satisfied. Preserve the minimal failing example and identify the next generator/architecture decision; do not conceal failures or declare unsupported behavior production-ready.

Out of scope

A permanent SDK repository or npm package, actual SDK release, Vue/frontend migration, refactoring PHP controllers, new multipart extraction, exhaustive ByJG coverage, new large CI matrices and PHP/C# SDK implementation.