The minimalistic document archiving platform.
import type { ApiContract } from '@papra/app-server/api/contract';
import * as v from 'valibot';
import { describe, expect, test } from 'vitest';
import { createContractClient } from './contract-client';
import { ApiHttpError, ApiResponseError } from './contract-client.errors';
import { createApiClient } from './http-client';
const getItemContract = {
operationId: 'call',
method: 'GET',
path: '/api/items',
responses: {
200: {
description: 'An item.',
content: { 'application/json': { schema: v.object({ name: v.string() }) } },
},
},
} as const satisfies ApiContract;
function createTestClient<const Contract extends ApiContract>(
contract: Contract,
respond: (request: Request) => Response | Promise<Response>,
) {
const requests: Request[] = [];
const { apiClient } = createApiClient({
apiBaseUrl: 'https://papra.example',
fetch: async (input, init) => {
const request = new Request(input, init);
requests.push(request);
return await respond(request);
},
});
return {
client: createContractClient({ contracts: { testContract: contract }, apiClient }),
requests,
};
}
describe('contract client', () => {
test('methods are named after operation IDs rather than registry exports', async () => {
const { client } = createTestClient({ ...getItemContract, operationId: 'getItem' }, () =>
Response.json({ name: 'Alice' }),
);
expect(Object.keys(client)).toEqual(['getItem']);
expect(await client.getItem()).toEqual({ name: 'Alice' });
});
test('duplicate operation IDs are rejected when building the client', () => {
const { apiClient } = createApiClient({ apiBaseUrl: 'https://papra.example' });
expect(() =>
createContractClient({
contracts: {
getItemContract,
duplicateItemContract: { ...getItemContract, path: '/api/other-items' },
},
apiClient,
}),
).toThrow('Duplicate operationId: call');
});
test('path and query values are encoded and request transformations are left to the server', async () => {
let transformations = 0;
const { client, requests } = createTestClient(
{
...getItemContract,
method: 'POST',
path: '/api/items/:id',
request: {
params: v.object({ id: v.string() }),
query: v.object({ search: v.string(), page: v.optional(v.string()) }),
body: {
'application/json': v.object({
count: v.pipe(
v.string(),
v.transform((value) => {
transformations++;
return Number(value) + 1;
}),
),
}),
},
},
responses: {
200: {
description: 'A parsed count.',
content: {
'application/json': {
schema: v.object({ count: v.pipe(v.string(), v.transform(Number)) }),
},
},
},
},
},
() =>
Response.json(
{ count: '3' },
{ headers: { 'Content-Type': 'application/json; charset=utf-8' } },
),
);
expect(
await client.call({
params: { id: 'a/b ?' },
query: { search: 'x&y', page: undefined },
body: { count: '2' },
}),
).toEqual({ count: 3 });
expect(transformations).toEqual(0);
expect(requests).toHaveLength(1);
const [request] = requests;
expect(request?.url).toEqual('https://papra.example/api/items/a%2Fb%20%3F?search=x%26y');
expect(request?.method).toEqual('POST');
expect(request?.headers.get('Content-Type')).toEqual('application/json');
expect(request?.headers.get('Accept')).toEqual('application/json');
expect(await request?.json()).toEqual({ count: '2' });
});
test('JSON string bodies are serialized rather than sent as unquoted text', async () => {
const { client, requests } = createTestClient(
{ ...getItemContract, method: 'PUT', request: { body: { 'application/json': v.string() } } },
() => Response.json({ name: 'Alice' }),
);
await client.call({ body: 'Alice' });
expect(await requests[0]?.text()).toEqual('"Alice"');
});
test('the actual success status selects its response schema', async () => {
const { client } = createTestClient(
{
...getItemContract,
responses: {
...getItemContract.responses,
201: {
description: 'A created item.',
content: { 'application/json': { schema: v.object({ id: v.number() }) } },
},
},
},
() => Response.json({ id: 123 }, { status: 201 }),
);
expect(await client.call()).toEqual({ id: 123 });
});
test('bodyless successful responses return undefined without parsing JSON', async () => {
const { client } = createTestClient(
{
operationId: 'call',
method: 'DELETE',
path: '/api/items',
responses: { 204: { description: 'Deleted.', content: {} } },
},
() => new Response(null, { status: 204 }),
);
expect(await client.call()).toEqual(undefined);
});
test('HTTP failures expose their status and JSON payload even when undeclared', async () => {
const data = { error: { code: 'auth.unauthorized', message: 'Unauthorized' } };
const { client } = createTestClient(getItemContract, () =>
Response.json(data, { status: 401 }),
);
const result = client.call();
await expect(result).rejects.toBeInstanceOf(ApiHttpError);
await expect(result).rejects.toMatchObject({
status: 401,
data,
method: 'GET',
path: '/api/items',
});
});
test('non-JSON HTTP failures retain their body and are not retried', async () => {
const { client, requests } = createTestClient(
getItemContract,
() => new Response('Bad gateway', { status: 502 }),
);
const result = client.call();
await expect(result).rejects.toBeInstanceOf(ApiHttpError);
await expect(result).rejects.toMatchObject({ status: 502, data: 'Bad gateway' });
expect(requests).toHaveLength(1);
});
test('a successful response with an invalid payload is a contract error, not an HTTP error', async () => {
const { client } = createTestClient(getItemContract, () => Response.json({ name: 123 }));
const result = client.call();
await expect(result).rejects.toBeInstanceOf(ApiResponseError);
await expect(result).rejects.toMatchObject({ status: 200, cause: { name: 'ValiError' } });
});
test('undeclared success statuses are rejected', async () => {
const { client } = createTestClient(getItemContract, () =>
Response.json({ name: 'Alice' }, { status: 201 }),
);
await expect(client.call()).rejects.toMatchObject({
name: 'ApiResponseError',
status: 201,
message: 'GET /api/items: Undeclared response status',
});
});
test('a JSON-looking response with an undeclared content type is rejected', async () => {
const { client } = createTestClient(
getItemContract,
() => new Response('{"name":"Alice"}', { headers: { 'Content-Type': 'text/plain' } }),
);
await expect(client.call()).rejects.toMatchObject({
name: 'ApiResponseError',
message: 'GET /api/items: Unexpected response Content-Type',
});
});
test('malformed JSON cannot satisfy even a string response schema', async () => {
const { client } = createTestClient(
{
...getItemContract,
responses: {
200: { description: 'A name.', content: { 'application/json': { schema: v.string() } } },
},
},
() => new Response('Alice', { headers: { 'Content-Type': 'application/json' } }),
);
await expect(client.call()).rejects.toBeInstanceOf(ApiResponseError);
});
test('unsupported request formats fail when building the client', () => {
expect(() =>
createTestClient(
{ ...getItemContract, method: 'POST', request: { body: { 'text/plain': v.string() } } },
() => Response.json({ name: 'Alice' }),
),
).toThrow('only JSON request bodies are supported');
});
test('unsupported response formats fail when building the client', () => {
expect(() =>
createTestClient(
{
...getItemContract,
responses: {
200: { description: 'A name.', content: { 'text/plain': { schema: v.string() } } },
},
},
() => new Response('Alice'),
),
).toThrow('only JSON or bodyless responses are supported');
});
test('path traversal values are rejected before a request is made', async () => {
const { client, requests } = createTestClient(
{
...getItemContract,
path: '/api/items/:id',
request: { params: v.object({ id: v.string() }) },
},
() => Response.json({ name: 'Alice' }),
);
await expect(client.call({ params: { id: '..' } })).rejects.toThrow(
'Invalid path parameter: id',
);
expect(requests).toHaveLength(0);
});
});