docs: client library migration guide

client/MIGRATION.md

@@ -0,0 +1,70 @@
+## @stacks/blockchain-api-client (<=7.x.x) → (8.x.x)
+
+## Breaking Changes
+
+This library is now generated with [openapi-typescript](https://openapi-ts.dev/openapi-fetch/) rather than [swagger-codegen](https://github.com/swagger-api/swagger-codegen). Several types which previously presented as the `any` type are now fixed, and the `@stacks/stacks-blockchain-api-types` package is no longer needed.
+
+#### Configuration & Middleware
+
+```ts
+// old:
+import { TransactionsApi, Configuration } from '@stacks/blockchain-api-client';
+const client = new TransactionsApi(new Configuration({
+  basePath: 'https://api.mainnet.hiro.so',
+  middleware: [{
+    pre({url, init}) {
+      init.headers = new Headers(init.headers);
+      init.headers.set('x-custom-header', 'custom-value');
+      return Promise.resolve({ url, init });
+    }
+  }]
+}));
+
+
+// new:
+import { createClient } from '@stacks/blockchain-api-client';
+const client = createClient({
+  baseUrl: 'https://api.mainnet.hiro.so'
+});
+client.use({
+  onRequest({request}) {
+    request.headers.set('x-custom-header', 'custom-value');
+    return request;
+  }
+});
+```
+
+#### Performing Requests
+
+```ts
+// old:
+const blockTxs = await client.getTransactionsByBlock({
+  heightOrHash: 2000,
+  limit: 20,
+  offset: 100
+});
+console.log('Block transactions:', blockTxs);
+
+// new:
+const { data: blockTxs } = await client.GET('/extended/v2/blocks/{height_or_hash}/transactions', { 
+  params: { 
+    path: { height_or_hash: 2000 }, 
+    query: { limit: 20, offset: 100 },
+  }
+});
+console.log('Block transactions:', blockTxs);
+```
+
+#### Referencing Types
+
+```ts
+// old:
+import { MempoolTransactionStatsResponse } from '@stacks/blockchain-api-client';
+let response: MempoolTransactionStatsResponse;
+response = await client.getMempoolTransactionStats();
+
+// new:
+import { OperationResponse } from '@stacks/blockchain-api-client';
+let response: OperationResponse['/extended/v1/tx/mempool/stats'];
+response = (await client.GET('/extended/v1/tx/mempool/stats')).data;
+```

client/README.md

@@ -3,6 +3,10 @@
 
 A JS Client for the Stacks Blockchain API
 
+## Breaking changes from (<=7.x.x) → (8.x.x)
+
+See [MIGRATION.md](./MIGRATION.md) for details.
+
 ## Features
 
 This package provides the ability to:

client/src/types.d.ts

@@ -1,9 +1,13 @@
-import type { operations } from "./generated/schema";
+import type { operations, paths } from './generated/schema';
 
 type Extract200Response<T> = T extends { 200: infer R } ? R : never;
 type ExtractOperationResponse<T extends keyof operations> = Extract200Response<operations[T]['responses']> extends { content: { 'application/json': infer U } } ? U : never;
+type PathResponse<T extends keyof paths> = paths[T]['get'] extends { responses: infer R } ? Extract200Response<R> extends { content: { 'application/json': infer U } } ? U : never : never;
+
 export type OperationResponse = {
   [K in keyof operations]: ExtractOperationResponse<K>;
+} & {
+  [P in keyof paths]: PathResponse<P>;
 };
 
 export type Transaction = OperationResponse['get_transaction_list']['results'][number];