@forinda/kickjs-client 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -12,12 +12,12 @@ interface RouteShapeLike {
12
12
  query: unknown;
13
13
  response: unknown;
14
14
  }
15
- type ApiMap = Record<string, RouteShapeLike>;
15
+ type ApiMap = object;
16
16
  /** HTTP verbs the route decorators produce. */
17
17
  type ClientMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
18
18
  /** Paths in the map registered under a given verb. */
19
19
  type PathsFor<Api extends ApiMap, M extends ClientMethod> = { [K in keyof Api]: K extends `${M} ${infer P}` ? P : never }[keyof Api];
20
- type ShapeOf<Api extends ApiMap, M extends ClientMethod, P extends string> = `${M} ${P}` extends keyof Api ? Api[`${M} ${P}`] : never;
20
+ type ShapeOf<Api extends ApiMap, M extends ClientMethod, P extends string> = `${M} ${P}` extends keyof Api ? Api[`${M} ${P}`] extends RouteShapeLike ? Api[`${M} ${P}`] : never : never;
21
21
  type ParamsField<T> = unknown extends T ? {
22
22
  params?: Record<string, string | number>;
23
23
  } : Record<string, never> extends T ? {
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":"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"}
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @forinda/kickjs-client v0.1.0
2
+ * @forinda/kickjs-client v0.1.1
3
3
  *
4
4
  * Copyright (c) Felix Orinda
5
5
  *
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// @forinda/kickjs-client — typed fetch client for KickJS APIs.\n//\n// Consumes the flat `KickRoutes.Api` map that `kick typegen` emits\n// (response-inference-design.md R3): keys are `'METHOD /path'`, values are\n// the route shapes (`params` / `body` / `query` / `response`). The client is\n// a ~150-line fetch wrapper — every type below exists so the CALL SITE\n// infers exactly:\n//\n// ```ts\n// const api = createClient<KickRoutes.Api>({ baseUrl: 'https://x/api/v1' })\n// const task = await api.post('/tasks/:id', { params: { id }, body })\n// // ^ the handler's actual response type\n// ```\n//\n// Runtime-neutral: fetch/URL/Headers only — browsers, node ≥ 20, Bun, Deno,\n// and edge workers (pairs with `@forinda/kickjs/web` on the server side).\n\n/**\n * The per-route shape `kick typegen` emits into `KickRoutes.Api`.\n * Deliberately re-declares (NOT imports) @forinda/kickjs's `RouteShape`:\n * frontends installing this client must never need the server package.\n * Keep the field list in sync with `RouteShape` in kickjs http/context.ts.\n */\nexport interface RouteShapeLike {\n params: unknown\n body: unknown\n query: unknown\n response: unknown\n}\n\ntype ApiMap = Record<string, RouteShapeLike>\n\n/** HTTP verbs the route decorators produce. */\nexport type ClientMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'\n\n/** Paths in the map registered under a given verb. */\ntype PathsFor<Api extends ApiMap, M extends ClientMethod> = {\n [K in keyof Api]: K extends `${M} ${infer P}` ? P : never\n}[keyof Api]\n\n// Fallback is `never` ON PURPOSE: P is already constrained to PathsFor, so a\n// failed key lookup means the map and the client's key math drifted — that\n// must fail loudly at the call site, not silently degrade to unknown.\ntype ShapeOf<\n Api extends ApiMap,\n M extends ClientMethod,\n P extends string,\n> = `${M} ${P}` extends keyof Api ? Api[`${M} ${P}`] : never\n\n// Paramless routes emit `params: {}` and unschema'd bodies emit\n// `body: unknown` — both become OPTIONAL fields; a concrete shape is\n// required so forgetting `params` on `/users/:id` is a type error.\ntype ParamsField<T> = unknown extends T\n ? { params?: Record<string, string | number> }\n : Record<string, never> extends T\n ? { params?: T }\n : { params: T }\n\ntype BodyField<T> = unknown extends T ? { body?: unknown } : { body: T }\n\n/** Loose fallback for routes without a statically-known query shape. */\ntype LooseQuery = Record<string, string | number | boolean | Array<string | number>>\n\n// Routes with a typegen-known query shape (Zod schema or the\n// @ApiQueryParams-derived filter/sort/q/page/limit object) constrain\n// `query` — sort fields autocomplete as '-createdAt' | 'createdAt' | …\ntype QueryField<T> = unknown extends T ? { query?: LooseQuery } : { query?: T }\n\nexport type RequestOptions<S extends RouteShapeLike> = {\n /** Extra headers merged over the client-level ones. */\n headers?: Record<string, string>\n /** AbortSignal for cancellation. */\n signal?: AbortSignal\n} & ParamsField<S['params']> &\n BodyField<S['body']> &\n QueryField<S['query']>\n\nexport interface ClientOptions {\n /**\n * Base URL INCLUDING the mount prefix + version the server adds at\n * bootstrap (default `/api/v1`) — `KickRoutes.Api` keys are module-mount\n * relative: `'GET /users/:id'` + baseUrl `https://x/api/v1`.\n */\n baseUrl: string\n /** Static headers, or a factory invoked per request (auth tokens). */\n headers?:\n | Record<string, string>\n | (() => Record<string, string> | Promise<Record<string, string>>)\n /**\n * Custom fetch — inject a platform fetch, a mock, or a KickJS web app's\n * own handler for network-free tests: `{ fetch: app.fetch }`.\n */\n fetch?: (request: Request) => Promise<Response>\n}\n\n/** Non-2xx responses throw this — carries the parsed body (RFC 9457 problem details when the server used `ctx.problem`). */\nexport class KickClientError extends Error {\n constructor(\n readonly status: number,\n readonly body: unknown,\n readonly response: Response,\n ) {\n super(\n typeof body === 'object' && body !== null && 'detail' in body\n ? String((body as { detail: unknown }).detail)\n : typeof body === 'object' && body !== null && 'error' in body\n ? String((body as { error: unknown }).error)\n : `Request failed with status ${status}`,\n )\n this.name = 'KickClientError'\n }\n}\n\nexport interface KickClient<Api extends ApiMap> {\n get<P extends PathsFor<Api, 'GET'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'GET', P>>,\n ): Promise<ShapeOf<Api, 'GET', P>['response']>\n post<P extends PathsFor<Api, 'POST'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'POST', P>>,\n ): Promise<ShapeOf<Api, 'POST', P>['response']>\n put<P extends PathsFor<Api, 'PUT'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'PUT', P>>,\n ): Promise<ShapeOf<Api, 'PUT', P>['response']>\n delete<P extends PathsFor<Api, 'DELETE'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'DELETE', P>>,\n ): Promise<ShapeOf<Api, 'DELETE', P>['response']>\n patch<P extends PathsFor<Api, 'PATCH'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'PATCH', P>>,\n ): Promise<ShapeOf<Api, 'PATCH', P>['response']>\n}\n\ninterface AnyRequestOptions {\n headers?: Record<string, string>\n signal?: AbortSignal\n query?: Record<string, unknown>\n params?: Record<string, string | number>\n body?: unknown\n}\n\n/** Substitute `:param` segments; throw on any left unfilled. */\nfunction fillPath(path: string, params?: Record<string, string | number>): string {\n const filled = path.replace(/:([A-Za-z0-9_]+)/g, (_, name: string) => {\n const value = params?.[name]\n if (value === undefined) {\n throw new Error(`@forinda/kickjs-client: missing path param ':${name}' for '${path}'`)\n }\n return encodeURIComponent(String(value))\n })\n return filled\n}\n\nfunction buildQuery(query?: Record<string, unknown>): string {\n if (!query) return ''\n const qs = new URLSearchParams()\n for (const [key, value] of Object.entries(query)) {\n if (value === undefined || value === null) continue\n if (Array.isArray(value)) for (const v of value) qs.append(key, String(v))\n else qs.append(key, String(value))\n }\n const s = qs.toString()\n return s ? `?${s}` : ''\n}\n\n/**\n * Create a typed client over a `KickRoutes.Api`-shaped map.\n * Generic-only consumption — no runtime dependency on the generated file.\n */\nexport function createClient<Api extends ApiMap>(options: ClientOptions): KickClient<Api> {\n const baseUrl = options.baseUrl.replace(/\\/$/, '')\n const doFetch = options.fetch ?? ((req: Request) => fetch(req))\n\n async function run(method: ClientMethod, path: string, opts: AnyRequestOptions = {}) {\n const clientHeaders =\n typeof options.headers === 'function' ? await options.headers() : (options.headers ?? {})\n const headers = new Headers({ ...clientHeaders, ...opts.headers })\n const hasBody = opts.body !== undefined\n if (hasBody && !headers.has('content-type')) {\n headers.set('content-type', 'application/json')\n }\n\n const url = `${baseUrl}${fillPath(path, opts.params)}${buildQuery(opts.query)}`\n const request = new Request(url, {\n method,\n headers,\n body: hasBody ? JSON.stringify(opts.body) : undefined,\n signal: opts.signal,\n })\n\n const response = await doFetch(request)\n const contentType = response.headers.get('content-type') ?? ''\n const body =\n response.status === 204\n ? undefined\n : contentType.includes('json')\n ? await response.json().catch(() => undefined)\n : await response.text()\n\n if (!response.ok) throw new KickClientError(response.status, body, response)\n return body\n }\n\n return {\n get: (path, opts) => run('GET', path, opts as AnyRequestOptions),\n post: (path, opts) => run('POST', path, opts as AnyRequestOptions),\n put: (path, opts) => run('PUT', path, opts as AnyRequestOptions),\n delete: (path, opts) => run('DELETE', path, opts as AnyRequestOptions),\n patch: (path, opts) => run('PATCH', path, opts as AnyRequestOptions),\n } as KickClient<Api>\n}\n\n/** Anything with a web-standard fetch — a `createWebApp()` result, a Worker, a mock. */\nexport interface FetchLike {\n fetch(request: Request): Promise<Response>\n}\n\n/**\n * Typed client over an in-process app — network-free full-stack tests:\n *\n * ```ts\n * const app = createWebApp({ h3, modules })\n * const api = createTestClient<KickRoutes.Api>(app)\n * expect(await api.get('/tasks/:id', { params: { id: '1' } })).toEqual(...)\n * ```\n *\n * `baseUrl` defaults to `http://test/api/v1` (the bootstrap default prefix);\n * override it when the server uses a custom `apiPrefix`/version.\n */\nexport function createTestClient<Api extends ApiMap>(\n app: FetchLike,\n options: Omit<ClientOptions, 'fetch' | 'baseUrl'> & { baseUrl?: string } = {},\n): KickClient<Api> {\n return createClient<Api>({\n ...options,\n // AFTER the spread — an explicit `baseUrl: undefined` key in options\n // must not clobber the default (spread copies undefined-valued keys).\n baseUrl: options.baseUrl ?? 'http://test/api/v1',\n fetch: (request) => app.fetch(request),\n })\n}\n"],"mappings":";;;;;;;;;;AAgGA,IAAa,gBAAb,cAAqC,KAAM,CAE9B,OACA,KACA,SAHX,YACE,OACA,KACA,SACA,CACA,MACE,OAAO,MAAS,UAAY,MAAiB,WAAY,KACrD,OAAQ,KAA6B,MAAM,EAC3C,OAAO,MAAS,UAAY,MAAiB,UAAW,KACtD,OAAQ,KAA4B,KAAK,EACzC,8BAA8B,QACtC,EAVS,KAAA,OAAA,OACA,KAAA,KAAA,KACA,KAAA,SAAA,SAST,KAAK,KAAO,iBACd,CACF,EAkCA,SAAS,SAAS,KAAc,OAAkD,CAQhF,OAPe,KAAK,QAAQ,qBAAsB,EAAG,OAAiB,CACpE,IAAM,MAAQ,SAAS,MACvB,GAAI,QAAU,IAAA,GACZ,MAAU,MAAM,gDAAgD,KAAK,SAAS,KAAK,EAAE,EAEvF,OAAO,mBAAmB,OAAO,KAAK,CAAC,CACzC,CACY,CACd,CAEA,SAAS,WAAW,MAAyC,CAC3D,GAAI,CAAC,MAAO,MAAO,GACnB,IAAM,GAAK,IAAI,gBACf,IAAK,GAAM,CAAC,IAAK,SAAU,OAAO,QAAQ,KAAK,EACzC,UAAiC,KACrC,GAAI,MAAM,QAAQ,KAAK,EAAG,IAAK,IAAM,KAAK,MAAO,GAAG,OAAO,IAAK,OAAO,CAAC,CAAC,OACpE,GAAG,OAAO,IAAK,OAAO,KAAK,CAAC,EAEnC,IAAM,EAAI,GAAG,SAAS,EACtB,OAAO,EAAI,IAAI,IAAM,EACvB,CAMA,SAAgB,aAAiC,QAAyC,CACxF,IAAM,QAAU,QAAQ,QAAQ,QAAQ,MAAO,EAAE,EAC3C,QAAU,QAAQ,QAAW,KAAiB,MAAM,GAAG,GAE7D,eAAe,IAAI,OAAsB,KAAc,KAA0B,CAAC,EAAG,CACnF,IAAM,cACJ,OAAO,QAAQ,SAAY,WAAa,MAAM,QAAQ,QAAQ,EAAK,QAAQ,SAAW,CAAC,EACnF,QAAU,IAAI,QAAQ,CAAE,GAAG,cAAe,GAAG,KAAK,OAAQ,CAAC,EAC3D,QAAU,KAAK,OAAS,IAAA,GAC1B,SAAW,CAAC,QAAQ,IAAI,cAAc,GACxC,QAAQ,IAAI,eAAgB,kBAAkB,EAGhD,IAAM,IAAM,GAAG,UAAU,SAAS,KAAM,KAAK,MAAM,IAAI,WAAW,KAAK,KAAK,IACtE,QAAU,IAAI,QAAQ,IAAK,CAC/B,OACA,QACA,KAAM,QAAU,KAAK,UAAU,KAAK,IAAI,EAAI,IAAA,GAC5C,OAAQ,KAAK,MACf,CAAC,EAEK,SAAW,MAAM,QAAQ,OAAO,EAChC,YAAc,SAAS,QAAQ,IAAI,cAAc,GAAK,GACtD,KACJ,SAAS,SAAW,IAChB,IAAA,GACA,YAAY,SAAS,MAAM,EACzB,MAAM,SAAS,KAAK,CAAC,CAAC,UAAY,IAAA,EAAS,EAC3C,MAAM,SAAS,KAAK,EAE5B,GAAI,CAAC,SAAS,GAAI,MAAM,IAAI,gBAAgB,SAAS,OAAQ,KAAM,QAAQ,EAC3E,OAAO,IACT,CAEA,MAAO,CACL,KAAM,KAAM,OAAS,IAAI,MAAO,KAAM,IAAyB,EAC/D,MAAO,KAAM,OAAS,IAAI,OAAQ,KAAM,IAAyB,EACjE,KAAM,KAAM,OAAS,IAAI,MAAO,KAAM,IAAyB,EAC/D,QAAS,KAAM,OAAS,IAAI,SAAU,KAAM,IAAyB,EACrE,OAAQ,KAAM,OAAS,IAAI,QAAS,KAAM,IAAyB,CACrE,CACF,CAmBA,SAAgB,iBACd,IACA,QAA2E,CAAC,EAC3D,CACjB,OAAO,aAAkB,CACvB,GAAG,QAGH,QAAS,QAAQ,SAAW,qBAC5B,MAAQ,SAAY,IAAI,MAAM,OAAO,CACvC,CAAC,CACH"}
1
+ {"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// @forinda/kickjs-client — typed fetch client for KickJS APIs.\n//\n// Consumes the flat `KickRoutes.Api` map that `kick typegen` emits\n// (response-inference-design.md R3): keys are `'METHOD /path'`, values are\n// the route shapes (`params` / `body` / `query` / `response`). The client is\n// a ~150-line fetch wrapper — every type below exists so the CALL SITE\n// infers exactly:\n//\n// ```ts\n// const api = createClient<KickRoutes.Api>({ baseUrl: 'https://x/api/v1' })\n// const task = await api.post('/tasks/:id', { params: { id }, body })\n// // ^ the handler's actual response type\n// ```\n//\n// Runtime-neutral: fetch/URL/Headers only — browsers, node ≥ 20, Bun, Deno,\n// and edge workers (pairs with `@forinda/kickjs/web` on the server side).\n\n/**\n * The per-route shape `kick typegen` emits into `KickRoutes.Api`.\n * Deliberately re-declares (NOT imports) @forinda/kickjs's `RouteShape`:\n * frontends installing this client must never need the server package.\n * Keep the field list in sync with `RouteShape` in kickjs http/context.ts.\n */\nexport interface RouteShapeLike {\n params: unknown\n body: unknown\n query: unknown\n response: unknown\n}\n\n// `object`, not `Record<string, RouteShapeLike>`: the generated\n// `KickRoutes.Api` is an INTERFACE, which has no string index signature and\n// would fail a Record constraint. Key/value conformance is guaranteed by the\n// generator; PathsFor/ShapeOf only rely on `keyof Api`.\ntype ApiMap = object\n\n/** HTTP verbs the route decorators produce. */\nexport type ClientMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'\n\n/** Paths in the map registered under a given verb. */\ntype PathsFor<Api extends ApiMap, M extends ClientMethod> = {\n [K in keyof Api]: K extends `${M} ${infer P}` ? P : never\n}[keyof Api]\n\n// Fallback is `never` ON PURPOSE: P is already constrained to PathsFor, so a\n// failed key lookup means the map and the client's key math drifted — that\n// must fail loudly at the call site, not silently degrade to unknown.\ntype ShapeOf<\n Api extends ApiMap,\n M extends ClientMethod,\n P extends string,\n> = `${M} ${P}` extends keyof Api\n ? Api[`${M} ${P}`] extends RouteShapeLike\n ? Api[`${M} ${P}`]\n : never\n : never\n\n// Paramless routes emit `params: {}` and unschema'd bodies emit\n// `body: unknown` — both become OPTIONAL fields; a concrete shape is\n// required so forgetting `params` on `/users/:id` is a type error.\ntype ParamsField<T> = unknown extends T\n ? { params?: Record<string, string | number> }\n : Record<string, never> extends T\n ? { params?: T }\n : { params: T }\n\ntype BodyField<T> = unknown extends T ? { body?: unknown } : { body: T }\n\n/** Loose fallback for routes without a statically-known query shape. */\ntype LooseQuery = Record<string, string | number | boolean | Array<string | number>>\n\n// Routes with a typegen-known query shape (Zod schema or the\n// @ApiQueryParams-derived filter/sort/q/page/limit object) constrain\n// `query` — sort fields autocomplete as '-createdAt' | 'createdAt' | …\ntype QueryField<T> = unknown extends T ? { query?: LooseQuery } : { query?: T }\n\nexport type RequestOptions<S extends RouteShapeLike> = {\n /** Extra headers merged over the client-level ones. */\n headers?: Record<string, string>\n /** AbortSignal for cancellation. */\n signal?: AbortSignal\n} & ParamsField<S['params']> &\n BodyField<S['body']> &\n QueryField<S['query']>\n\nexport interface ClientOptions {\n /**\n * Base URL INCLUDING the mount prefix + version the server adds at\n * bootstrap (default `/api/v1`) — `KickRoutes.Api` keys are module-mount\n * relative: `'GET /users/:id'` + baseUrl `https://x/api/v1`.\n */\n baseUrl: string\n /** Static headers, or a factory invoked per request (auth tokens). */\n headers?:\n | Record<string, string>\n | (() => Record<string, string> | Promise<Record<string, string>>)\n /**\n * Custom fetch — inject a platform fetch, a mock, or a KickJS web app's\n * own handler for network-free tests: `{ fetch: app.fetch }`.\n */\n fetch?: (request: Request) => Promise<Response>\n}\n\n/** Non-2xx responses throw this — carries the parsed body (RFC 9457 problem details when the server used `ctx.problem`). */\nexport class KickClientError extends Error {\n constructor(\n readonly status: number,\n readonly body: unknown,\n readonly response: Response,\n ) {\n super(\n typeof body === 'object' && body !== null && 'detail' in body\n ? String((body as { detail: unknown }).detail)\n : typeof body === 'object' && body !== null && 'error' in body\n ? String((body as { error: unknown }).error)\n : `Request failed with status ${status}`,\n )\n this.name = 'KickClientError'\n }\n}\n\nexport interface KickClient<Api extends ApiMap> {\n get<P extends PathsFor<Api, 'GET'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'GET', P>>,\n ): Promise<ShapeOf<Api, 'GET', P>['response']>\n post<P extends PathsFor<Api, 'POST'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'POST', P>>,\n ): Promise<ShapeOf<Api, 'POST', P>['response']>\n put<P extends PathsFor<Api, 'PUT'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'PUT', P>>,\n ): Promise<ShapeOf<Api, 'PUT', P>['response']>\n delete<P extends PathsFor<Api, 'DELETE'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'DELETE', P>>,\n ): Promise<ShapeOf<Api, 'DELETE', P>['response']>\n patch<P extends PathsFor<Api, 'PATCH'> & string>(\n path: P,\n options?: RequestOptions<ShapeOf<Api, 'PATCH', P>>,\n ): Promise<ShapeOf<Api, 'PATCH', P>['response']>\n}\n\ninterface AnyRequestOptions {\n headers?: Record<string, string>\n signal?: AbortSignal\n query?: Record<string, unknown>\n params?: Record<string, string | number>\n body?: unknown\n}\n\n/** Substitute `:param` segments; throw on any left unfilled. */\nfunction fillPath(path: string, params?: Record<string, string | number>): string {\n const filled = path.replace(/:([A-Za-z0-9_]+)/g, (_, name: string) => {\n const value = params?.[name]\n if (value === undefined) {\n throw new Error(`@forinda/kickjs-client: missing path param ':${name}' for '${path}'`)\n }\n return encodeURIComponent(String(value))\n })\n return filled\n}\n\nfunction buildQuery(query?: Record<string, unknown>): string {\n if (!query) return ''\n const qs = new URLSearchParams()\n for (const [key, value] of Object.entries(query)) {\n if (value === undefined || value === null) continue\n if (Array.isArray(value)) for (const v of value) qs.append(key, String(v))\n else qs.append(key, String(value))\n }\n const s = qs.toString()\n return s ? `?${s}` : ''\n}\n\n/**\n * Create a typed client over a `KickRoutes.Api`-shaped map.\n * Generic-only consumption — no runtime dependency on the generated file.\n */\nexport function createClient<Api extends ApiMap>(options: ClientOptions): KickClient<Api> {\n const baseUrl = options.baseUrl.replace(/\\/$/, '')\n const doFetch = options.fetch ?? ((req: Request) => fetch(req))\n\n async function run(method: ClientMethod, path: string, opts: AnyRequestOptions = {}) {\n const clientHeaders =\n typeof options.headers === 'function' ? await options.headers() : (options.headers ?? {})\n const headers = new Headers({ ...clientHeaders, ...opts.headers })\n const hasBody = opts.body !== undefined\n if (hasBody && !headers.has('content-type')) {\n headers.set('content-type', 'application/json')\n }\n\n const url = `${baseUrl}${fillPath(path, opts.params)}${buildQuery(opts.query)}`\n const request = new Request(url, {\n method,\n headers,\n body: hasBody ? JSON.stringify(opts.body) : undefined,\n signal: opts.signal,\n })\n\n const response = await doFetch(request)\n const contentType = response.headers.get('content-type') ?? ''\n const body =\n response.status === 204\n ? undefined\n : contentType.includes('json')\n ? await response.json().catch(() => undefined)\n : await response.text()\n\n if (!response.ok) throw new KickClientError(response.status, body, response)\n return body\n }\n\n return {\n get: (path, opts) => run('GET', path, opts as AnyRequestOptions),\n post: (path, opts) => run('POST', path, opts as AnyRequestOptions),\n put: (path, opts) => run('PUT', path, opts as AnyRequestOptions),\n delete: (path, opts) => run('DELETE', path, opts as AnyRequestOptions),\n patch: (path, opts) => run('PATCH', path, opts as AnyRequestOptions),\n } as KickClient<Api>\n}\n\n/** Anything with a web-standard fetch — a `createWebApp()` result, a Worker, a mock. */\nexport interface FetchLike {\n fetch(request: Request): Promise<Response>\n}\n\n/**\n * Typed client over an in-process app — network-free full-stack tests:\n *\n * ```ts\n * const app = createWebApp({ h3, modules })\n * const api = createTestClient<KickRoutes.Api>(app)\n * expect(await api.get('/tasks/:id', { params: { id: '1' } })).toEqual(...)\n * ```\n *\n * `baseUrl` defaults to `http://test/api/v1` (the bootstrap default prefix);\n * override it when the server uses a custom `apiPrefix`/version.\n */\nexport function createTestClient<Api extends ApiMap>(\n app: FetchLike,\n options: Omit<ClientOptions, 'fetch' | 'baseUrl'> & { baseUrl?: string } = {},\n): KickClient<Api> {\n return createClient<Api>({\n ...options,\n // AFTER the spread — an explicit `baseUrl: undefined` key in options\n // must not clobber the default (spread copies undefined-valued keys).\n baseUrl: options.baseUrl ?? 'http://test/api/v1',\n fetch: (request) => app.fetch(request),\n })\n}\n"],"mappings":";;;;;;;;;;AAwGA,IAAa,gBAAb,cAAqC,KAAM,CAE9B,OACA,KACA,SAHX,YACE,OACA,KACA,SACA,CACA,MACE,OAAO,MAAS,UAAY,MAAiB,WAAY,KACrD,OAAQ,KAA6B,MAAM,EAC3C,OAAO,MAAS,UAAY,MAAiB,UAAW,KACtD,OAAQ,KAA4B,KAAK,EACzC,8BAA8B,QACtC,EAVS,KAAA,OAAA,OACA,KAAA,KAAA,KACA,KAAA,SAAA,SAST,KAAK,KAAO,iBACd,CACF,EAkCA,SAAS,SAAS,KAAc,OAAkD,CAQhF,OAPe,KAAK,QAAQ,qBAAsB,EAAG,OAAiB,CACpE,IAAM,MAAQ,SAAS,MACvB,GAAI,QAAU,IAAA,GACZ,MAAU,MAAM,gDAAgD,KAAK,SAAS,KAAK,EAAE,EAEvF,OAAO,mBAAmB,OAAO,KAAK,CAAC,CACzC,CACY,CACd,CAEA,SAAS,WAAW,MAAyC,CAC3D,GAAI,CAAC,MAAO,MAAO,GACnB,IAAM,GAAK,IAAI,gBACf,IAAK,GAAM,CAAC,IAAK,SAAU,OAAO,QAAQ,KAAK,EACzC,UAAiC,KACrC,GAAI,MAAM,QAAQ,KAAK,EAAG,IAAK,IAAM,KAAK,MAAO,GAAG,OAAO,IAAK,OAAO,CAAC,CAAC,OACpE,GAAG,OAAO,IAAK,OAAO,KAAK,CAAC,EAEnC,IAAM,EAAI,GAAG,SAAS,EACtB,OAAO,EAAI,IAAI,IAAM,EACvB,CAMA,SAAgB,aAAiC,QAAyC,CACxF,IAAM,QAAU,QAAQ,QAAQ,QAAQ,MAAO,EAAE,EAC3C,QAAU,QAAQ,QAAW,KAAiB,MAAM,GAAG,GAE7D,eAAe,IAAI,OAAsB,KAAc,KAA0B,CAAC,EAAG,CACnF,IAAM,cACJ,OAAO,QAAQ,SAAY,WAAa,MAAM,QAAQ,QAAQ,EAAK,QAAQ,SAAW,CAAC,EACnF,QAAU,IAAI,QAAQ,CAAE,GAAG,cAAe,GAAG,KAAK,OAAQ,CAAC,EAC3D,QAAU,KAAK,OAAS,IAAA,GAC1B,SAAW,CAAC,QAAQ,IAAI,cAAc,GACxC,QAAQ,IAAI,eAAgB,kBAAkB,EAGhD,IAAM,IAAM,GAAG,UAAU,SAAS,KAAM,KAAK,MAAM,IAAI,WAAW,KAAK,KAAK,IACtE,QAAU,IAAI,QAAQ,IAAK,CAC/B,OACA,QACA,KAAM,QAAU,KAAK,UAAU,KAAK,IAAI,EAAI,IAAA,GAC5C,OAAQ,KAAK,MACf,CAAC,EAEK,SAAW,MAAM,QAAQ,OAAO,EAChC,YAAc,SAAS,QAAQ,IAAI,cAAc,GAAK,GACtD,KACJ,SAAS,SAAW,IAChB,IAAA,GACA,YAAY,SAAS,MAAM,EACzB,MAAM,SAAS,KAAK,CAAC,CAAC,UAAY,IAAA,EAAS,EAC3C,MAAM,SAAS,KAAK,EAE5B,GAAI,CAAC,SAAS,GAAI,MAAM,IAAI,gBAAgB,SAAS,OAAQ,KAAM,QAAQ,EAC3E,OAAO,IACT,CAEA,MAAO,CACL,KAAM,KAAM,OAAS,IAAI,MAAO,KAAM,IAAyB,EAC/D,MAAO,KAAM,OAAS,IAAI,OAAQ,KAAM,IAAyB,EACjE,KAAM,KAAM,OAAS,IAAI,MAAO,KAAM,IAAyB,EAC/D,QAAS,KAAM,OAAS,IAAI,SAAU,KAAM,IAAyB,EACrE,OAAQ,KAAM,OAAS,IAAI,QAAS,KAAM,IAAyB,CACrE,CACF,CAmBA,SAAgB,iBACd,IACA,QAA2E,CAAC,EAC3D,CACjB,OAAO,aAAkB,CACvB,GAAG,QAGH,QAAS,QAAQ,SAAW,qBAC5B,MAAQ,SAAY,IAAI,MAAM,OAAO,CACvC,CAAC,CACH"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@forinda/kickjs-client",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Typed fetch client for KickJS APIs — end-to-end response types from the kick typegen KickRoutes augmentation",
5
5
  "keywords": [
6
6
  "kickjs",
@@ -11,12 +11,12 @@
11
11
  "api-client"
12
12
  ],
13
13
  "type": "module",
14
- "main": "dist/index.mjs",
15
- "types": "dist/index.d.mts",
14
+ "main": "dist/index.js",
15
+ "types": "dist/index.d.ts",
16
16
  "exports": {
17
17
  ".": {
18
- "import": "./dist/index.mjs",
19
- "types": "./dist/index.d.mts"
18
+ "types": "./dist/index.d.ts",
19
+ "import": "./dist/index.js"
20
20
  }
21
21
  },
22
22
  "files": [