@llamaduck/forgejo-ts 11.0.10 → 11.0.12

package/README.md

@@ -16,141 +16,139 @@ pnpm add @llamaduck/forgejo-ts
 
 ## Usage
 
-### Basic Configuration
+### Basic Usage
+
+Create a client and start making API calls:
 
 ```typescript
-import { configure, RepositoryService, UserService } from '@llamaduck/forgejo-ts';
+import { createClient, createConfig, getVersion, repoSearch } from '@llamaduck/forgejo-ts';
+
+// Create a client
+const client = createClient(createConfig({
+  baseUrl: 'https://codeberg.org/api/v1',
+  headers: { Authorization: 'token your-api-token' }
+}));
 
-// Configure the client
-configure({
-  baseUrl: 'https://your-forgejo-instance.com/api/v1',
-  token: 'your-api-token', // Optional: for authenticated requests
-});
+// Make API calls - pass the client in options
+const version = await getVersion({ client });
+console.log('Server version:', version.data?.version);
 
-// Now use any service
-const repos = await RepositoryService.repoSearch({ q: 'hello' });
-console.log(repos);
+const repos = await repoSearch({ query: { q: 'typescript', limit: 10 } }, { client });
+console.log('Found repos:', repos.data);
 ```
 
-### Authentication Options
+### Multiple Clients
+
+You can create multiple independent client instances:
 
 ```typescript
-import { configure } from '@llamaduck/forgejo-ts';
+import { createClient, createConfig, repoSearch } from '@llamaduck/forgejo-ts';
 
-// Token authentication (recommended)
-configure({
-  baseUrl: 'https://your-forgejo-instance.com/api/v1',
-  token: 'your-personal-access-token',
-});
+const clientA = createClient(createConfig({
+  baseUrl: 'https://codeberg.org/api/v1',
+  headers: { Authorization: 'token token-a' }
+}));
 
-// Basic authentication
-configure({
-  baseUrl: 'https://your-forgejo-instance.com/api/v1',
-  username: 'your-username',
-  password: 'your-password',
-});
-```
+const clientB = createClient(createConfig({
+  baseUrl: 'https://gitea.com/api/v1',
+  headers: { Authorization: 'token token-b' }
+}));
 
-### Direct OpenAPI Configuration
+// Use different clients for different requests
+const reposA = await repoSearch({ query: { q: 'test' } }, { client: clientA });
+const reposB = await repoSearch({ query: { q: 'test' } }, { client: clientB });
+```
 
-For more control, you can configure the OpenAPI object directly:
+### Authentication
 
 ```typescript
-import { OpenAPI } from '@llamaduck/forgejo-ts';
+import { createClient, createConfig } from '@llamaduck/forgejo-ts';
 
-OpenAPI.BASE = 'https://your-forgejo-instance.com/api/v1';
-OpenAPI.TOKEN = 'your-api-token';
+// Token authentication (recommended)
+const client = createClient(createConfig({
+  baseUrl: 'https://codeberg.org/api/v1',
+  headers: { Authorization: 'token your-personal-access-token' }
+}));
 
-// Or use a function for dynamic token retrieval
-OpenAPI.TOKEN = async () => {
-  return getTokenFromSomewhere();
-};
+// Basic authentication
+const auth = btoa('username:password');
+const client = createClient(createConfig({
+  baseUrl: 'https://codeberg.org/api/v1',
+  headers: { Authorization: `Basic ${auth}` }
+}));
 ```
 
-### Using Services
+## API Reference
 
-All API endpoints are organized into services:
+All API functions are exported directly from the package:
 
 ```typescript
 import {
-  RepositoryService,
-  UserService,
-  OrganizationService,
-  IssueService,
-  AdminService,
-  // ... and more
+  // Repositories
+  repoSearch,
+  repoGet,
+  userListRepos,
+  
+  // Users
+  userGetCurrent,
+  userGet,
+  
+  // Issues
+  issueSearch,
+  issueCreateIssue,
+  
+  // Organizations
+  orgGet,
+  
+  // And many more...
 } from '@llamaduck/forgejo-ts';
-
-// Get current user
-const user = await UserService.userGetCurrent();
-
-// List repositories
-const repos = await RepositoryService.repoSearch({
-  q: 'typescript',
-  limit: 10,
-});
-
-// Create an issue
-const issue = await IssueService.issueCreateIssue({
-  owner: 'username',
-  repo: 'repo-name',
-  body: {
-    title: 'Bug report',
-    body: 'Description of the bug',
-  },
-});
 ```
 
-### Error Handling
+Each function accepts:
+1. **Data/params** - The request data (path params, query params, body)
+2. **Options** (optional) - Request options including the `client` instance
 
+Example:
 ```typescript
-import { ApiError, RepositoryService } from '@llamaduck/forgejo-ts';
+// Search repositories
+const repos = await repoSearch(
+  { query: { q: 'typescript', limit: 10 } },
+  { client }
+);
+
+// Get a specific repository
+const repo = await repoGet(
+  { path: { owner: 'forgejo', repo: 'forgejo' } },
+  { client }
+);
 
-try {
-  const repo = await RepositoryService.repoGet({
-    owner: 'user',
-    repo: 'nonexistent',
-  });
-} catch (error) {
-  if (error instanceof ApiError) {
-    console.error('API Error:', error.status, error.message);
-    console.error('Response body:', error.body);
-  }
-}
+// Create an issue
+const issue = await issueCreateIssue(
+  { path: { owner: 'user', repo: 'repo' } },
+  { body: { title: 'Bug report', body: 'Description' } },
+  { client }
+);
 ```
 
-### Canceling Requests
+### Error Handling
 
 ```typescript
-import { RepositoryService, CancelError } from '@llamaduck/forgejo-ts';
-
-const request = RepositoryService.repoSearch({ q: 'test' });
-
-// Cancel the request
-request.cancel();
+import { repoGet } from '@llamaduck/forgejo-ts';
 
 try {
-  await request;
+  const repo = await repoGet(
+    { path: { owner: 'user', repo: 'nonexistent' } },
+    { client }
+  );
 } catch (error) {
-  if (error instanceof CancelError) {
-    console.log('Request was canceled');
+  if (error.status === 404) {
+    console.error('Repository not found');
+  } else {
+    console.error('API Error:', error);
   }
 }
 ```
 
-## Available Services
-
-- `ActivitypubService` - ActivityPub federation endpoints
-- `AdminService` - Administration endpoints (requires admin access)
-- `IssueService` - Issues and pull requests
-- `MiscellaneousService` - Miscellaneous endpoints (version, settings, etc.)
-- `NotificationService` - User notifications
-- `OrganizationService` - Organizations and teams
-- `PackageService` - Package registry
-- `RepositoryService` - Repositories, branches, commits, files
-- `SettingsService` - Instance settings
-- `UserService` - Users, followers, tokens, keys
-
 ## Version Information
 
 ```typescript
@@ -189,8 +187,6 @@ FORGEJO_VERSION=14.0.2 npm run generate
 npm run build
 ```
 
-The script fetches the Swagger spec directly from Codeberg. 
-
 ## Configuration
 
 The `config.json` file specifies which major versions to track:
@@ -206,7 +202,7 @@ When Forgejo releases a new major version (e.g., v15), update this file to chang
 
 ## Contributing
 
-Contributions are welcome! Please note that the `src/generated/` directory is auto-generated and should not be manually edited.
+Contributions are welcome! Please note that the `src/` directory is auto-generated and should not be manually edited.
 
 ## License
 

package/client.d.ts

@@ -0,0 +1 @@
+export * from "./dist/client/index";

package/client.js

@@ -0,0 +1 @@
+module.exports = require("./dist/client/index.js");

package/client.mjs

@@ -0,0 +1 @@
+export * from "./dist/client/index.mjs";

package/dist/client/index.d.mts

@@ -0,0 +1,339 @@
+import { CreateAxiosDefaults, AxiosStatic, AxiosInstance, AxiosRequestHeaders, AxiosResponse, AxiosError } from 'axios';
+
+type AuthToken = string | undefined;
+interface Auth {
+    /**
+     * Which part of the request do we use to send the auth?
+     *
+     * @default 'header'
+     */
+    in?: 'header' | 'query' | 'cookie';
+    /**
+     * Header or query parameter name.
+     *
+     * @default 'Authorization'
+     */
+    name?: string;
+    scheme?: 'basic' | 'bearer';
+    type: 'apiKey' | 'http';
+}
+
+interface SerializerOptions<T> {
+    /**
+     * @default true
+     */
+    explode: boolean;
+    style: T;
+}
+type ArrayStyle = 'form' | 'spaceDelimited' | 'pipeDelimited';
+type ObjectStyle = 'form' | 'deepObject';
+
+type QuerySerializer = (query: Record<string, unknown>) => string;
+type BodySerializer = (body: any) => any;
+type QuerySerializerOptionsObject = {
+    allowReserved?: boolean;
+    array?: Partial<SerializerOptions<ArrayStyle>>;
+    object?: Partial<SerializerOptions<ObjectStyle>>;
+};
+type QuerySerializerOptions = QuerySerializerOptionsObject & {
+    /**
+     * Per-parameter serialization overrides. When provided, these settings
+     * override the global array/object settings for specific parameter names.
+     */
+    parameters?: Record<string, QuerySerializerOptionsObject>;
+};
+declare const formDataBodySerializer: {
+    bodySerializer: <T extends Record<string, any> | Array<Record<string, any>>>(body: T) => FormData;
+};
+declare const jsonBodySerializer: {
+    bodySerializer: <T>(body: T) => string;
+};
+declare const urlSearchParamsBodySerializer: {
+    bodySerializer: <T extends Record<string, any> | Array<Record<string, any>>>(body: T) => string;
+};
+
+type Slot = 'body' | 'headers' | 'path' | 'query';
+type Field = {
+    in: Exclude<Slot, 'body'>;
+    /**
+     * Field name. This is the name we want the user to see and use.
+     */
+    key: string;
+    /**
+     * Field mapped name. This is the name we want to use in the request.
+     * If omitted, we use the same value as `key`.
+     */
+    map?: string;
+} | {
+    in: Extract<Slot, 'body'>;
+    /**
+     * Key isn't required for bodies.
+     */
+    key?: string;
+    map?: string;
+} | {
+    /**
+     * Field name. This is the name we want the user to see and use.
+     */
+    key: string;
+    /**
+     * Field mapped name. This is the name we want to use in the request.
+     * If `in` is omitted, `map` aliases `key` to the transport layer.
+     */
+    map: Slot;
+};
+interface Fields {
+    allowExtra?: Partial<Record<Slot, boolean>>;
+    args?: ReadonlyArray<Field>;
+}
+type FieldsConfig = ReadonlyArray<Field | Fields>;
+interface Params {
+    body: unknown;
+    headers: Record<string, unknown>;
+    path: Record<string, unknown>;
+    query: Record<string, unknown>;
+}
+declare const buildClientParams: (args: ReadonlyArray<unknown>, fields: FieldsConfig) => Params;
+
+/**
+ * JSON-friendly union that mirrors what Pinia Colada can hash.
+ */
+type JsonValue = null | string | number | boolean | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Normalizes any accepted value into a JSON-friendly shape for query keys.
+ */
+declare const serializeQueryKeyValue: (value: unknown) => JsonValue | undefined;
+
+type HttpMethod = 'connect' | 'delete' | 'get' | 'head' | 'options' | 'patch' | 'post' | 'put' | 'trace';
+type Client$1<RequestFn = never, Config = unknown, MethodFn = never, BuildUrlFn = never, SseFn = never> = {
+    /**
+     * Returns the final request URL.
+     */
+    buildUrl: BuildUrlFn;
+    getConfig: () => Config;
+    request: RequestFn;
+    setConfig: (config: Config) => Config;
+} & {
+    [K in HttpMethod]: MethodFn;
+} & ([SseFn] extends [never] ? {
+    sse?: never;
+} : {
+    sse: {
+        [K in HttpMethod]: SseFn;
+    };
+});
+interface Config$1 {
+    /**
+     * Auth token or a function returning auth token. The resolved value will be
+     * added to the request payload as defined by its `security` array.
+     */
+    auth?: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken;
+    /**
+     * A function for serializing request body parameter. By default,
+     * {@link JSON.stringify()} will be used.
+     */
+    bodySerializer?: BodySerializer | null;
+    /**
+     * An object containing any HTTP headers that you want to pre-populate your
+     * `Headers` object with.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
+     */
+    headers?: RequestInit['headers'] | Record<string, string | number | boolean | (string | number | boolean)[] | null | undefined | unknown>;
+    /**
+     * The request method.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
+     */
+    method?: Uppercase<HttpMethod>;
+    /**
+     * A function for serializing request query parameters. By default, arrays
+     * will be exploded in form style, objects will be exploded in deepObject
+     * style, and reserved characters are percent-encoded.
+     *
+     * This method will have no effect if the native `paramsSerializer()` Axios
+     * API function is used.
+     *
+     * {@link https://swagger.io/docs/specification/serialization/#query View examples}
+     */
+    querySerializer?: QuerySerializer | QuerySerializerOptions;
+    /**
+     * A function validating request data. This is useful if you want to ensure
+     * the request conforms to the desired shape, so it can be safely sent to
+     * the server.
+     */
+    requestValidator?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function transforming response data before it's returned. This is useful
+     * for post-processing data, e.g. converting ISO strings into Date objects.
+     */
+    responseTransformer?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function validating response data. This is useful if you want to ensure
+     * the response conforms to the desired shape, so it can be safely passed to
+     * the transformers and returned to the user.
+     */
+    responseValidator?: (data: unknown) => Promise<unknown>;
+}
+
+type ServerSentEventsOptions<TData = unknown> = Omit<RequestInit, 'method'> & Pick<Config$1, 'method' | 'responseTransformer' | 'responseValidator'> & {
+    /**
+     * Fetch API implementation. You can use this option to provide a custom
+     * fetch instance.
+     *
+     * @default globalThis.fetch
+     */
+    fetch?: typeof fetch;
+    /**
+     * Implementing clients can call request interceptors inside this hook.
+     */
+    onRequest?: (url: string, init: RequestInit) => Promise<Request>;
+    /**
+     * Callback invoked when a network or parsing error occurs during streaming.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @param error The error that occurred.
+     */
+    onSseError?: (error: unknown) => void;
+    /**
+     * Callback invoked when an event is streamed from the server.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @param event Event streamed from the server.
+     * @returns Nothing (void).
+     */
+    onSseEvent?: (event: StreamEvent<TData>) => void;
+    serializedBody?: RequestInit['body'];
+    /**
+     * Default retry delay in milliseconds.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @default 3000
+     */
+    sseDefaultRetryDelay?: number;
+    /**
+     * Maximum number of retry attempts before giving up.
+     */
+    sseMaxRetryAttempts?: number;
+    /**
+     * Maximum retry delay in milliseconds.
+     *
+     * Applies only when exponential backoff is used.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @default 30000
+     */
+    sseMaxRetryDelay?: number;
+    /**
+     * Optional sleep function for retry backoff.
+     *
+     * Defaults to using `setTimeout`.
+     */
+    sseSleepFn?: (ms: number) => Promise<void>;
+    url: string;
+};
+interface StreamEvent<TData = unknown> {
+    data: TData;
+    event?: string;
+    id?: string;
+    retry?: number;
+}
+type ServerSentEventsResult<TData = unknown, TReturn = void, TNext = unknown> = {
+    stream: AsyncGenerator<TData extends Record<string, unknown> ? TData[keyof TData] : TData, TReturn, TNext>;
+};
+
+interface Config<T extends ClientOptions = ClientOptions> extends Omit<CreateAxiosDefaults, 'auth' | 'baseURL' | 'headers' | 'method'>, Config$1 {
+    /**
+     * Axios implementation. You can use this option to provide either an
+     * `AxiosStatic` or an `AxiosInstance`.
+     *
+     * @default axios
+     */
+    axios?: AxiosStatic | AxiosInstance;
+    /**
+     * Base URL for all requests made by this client.
+     */
+    baseURL?: T['baseURL'];
+    /**
+     * An object containing any HTTP headers that you want to pre-populate your
+     * `Headers` object with.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
+     */
+    headers?: AxiosRequestHeaders | Record<string, string | number | boolean | (string | number | boolean)[] | null | undefined | unknown>;
+    /**
+     * Throw an error instead of returning it in the response?
+     *
+     * @default false
+     */
+    throwOnError?: T['throwOnError'];
+}
+interface RequestOptions<TData = unknown, ThrowOnError extends boolean = boolean, Url extends string = string> extends Config<{
+    throwOnError: ThrowOnError;
+}>, Pick<ServerSentEventsOptions<TData>, 'onSseError' | 'onSseEvent' | 'sseDefaultRetryDelay' | 'sseMaxRetryAttempts' | 'sseMaxRetryDelay'> {
+    /**
+     * Any body that you want to add to your request.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/fetch#body}
+     */
+    body?: unknown;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    /**
+     * Security mechanism(s) to use for the request.
+     */
+    security?: ReadonlyArray<Auth>;
+    url: Url;
+}
+interface ClientOptions {
+    baseURL?: string;
+    throwOnError?: boolean;
+}
+type RequestResult<TData = unknown, TError = unknown, ThrowOnError extends boolean = boolean> = ThrowOnError extends true ? Promise<AxiosResponse<TData extends Record<string, unknown> ? TData[keyof TData] : TData>> : Promise<(AxiosResponse<TData extends Record<string, unknown> ? TData[keyof TData] : TData> & {
+    error: undefined;
+}) | (AxiosError<TError extends Record<string, unknown> ? TError[keyof TError] : TError> & {
+    data: undefined;
+    error: TError extends Record<string, unknown> ? TError[keyof TError] : TError;
+})>;
+type MethodFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false>(options: Omit<RequestOptions<TData, ThrowOnError>, 'method'>) => RequestResult<TData, TError, ThrowOnError>;
+type SseFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false>(options: Omit<RequestOptions<TData, ThrowOnError>, 'method'>) => Promise<ServerSentEventsResult<TData, TError>>;
+type RequestFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false>(options: Omit<RequestOptions<TData, ThrowOnError>, 'method'> & Pick<Required<RequestOptions<TData, ThrowOnError>>, 'method'>) => RequestResult<TData, TError, ThrowOnError>;
+type BuildUrlFn = <TData extends {
+    body?: unknown;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    url: string;
+}>(options: TData & Options<TData>) => string;
+type Client = Client$1<RequestFn, Config, MethodFn, BuildUrlFn, SseFn> & {
+    instance: AxiosInstance;
+};
+/**
+ * The `createClientConfig()` function will be called on client initialization
+ * and the returned object will become the client's initial configuration.
+ *
+ * You may want to initialize your client this way instead of calling
+ * `setConfig()`. This is useful for example if you're using Next.js
+ * to ensure your client always has the correct values.
+ */
+type CreateClientConfig<T extends ClientOptions = ClientOptions> = (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;
+interface TDataShape {
+    body?: unknown;
+    headers?: unknown;
+    path?: unknown;
+    query?: unknown;
+    url: string;
+}
+type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
+type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = OmitKeys<RequestOptions<TResponse, ThrowOnError>, 'body' | 'path' | 'query' | 'url'> & ([TData] extends [never] ? unknown : Omit<TData, 'url'>);
+
+declare const createClient: (config?: Config) => Client;
+
+declare const createConfig: <T extends ClientOptions = ClientOptions>(override?: Config<Omit<ClientOptions, keyof T> & T>) => Config<Omit<ClientOptions, keyof T> & T>;
+
+export { type Auth, type Client, type ClientOptions, type Config, type CreateClientConfig, type Options, type QuerySerializerOptions, type RequestOptions, type RequestResult, type TDataShape, buildClientParams, createClient, createConfig, formDataBodySerializer, jsonBodySerializer, serializeQueryKeyValue, urlSearchParamsBodySerializer };