chore(internal): codegen related update (#206)

Author: stainless-app[bot]

MIGRATION.md

@@ -286,49 +286,48 @@ The `headers` property on `APIError` objects is now an instance of the Web [Head
 
 ### Removed exports
 
-#### `Response`
-
-```typescript
-// Before
-import { Response } from 'writer-sdk';
-
-// After
-// `Response` must now come from the builtin types
-```
-
 #### Resource classes
 
-If you were importing resource classes from the root package then you must now import them from the file they are defined in:
+If you were importing resource classes from the root package then you must now import them from the file they are defined in.
+This was never valid at the type level and only worked in CommonJS files.
 
 ```typescript
 // Before
-import { Applications } from 'writer-sdk';
+const { Applications } = require('writer-sdk');
 
 // After
-import { Applications } from 'writer-sdk/resources/applications/applications';
+const { Writer } = require('writer-sdk');
+Writer.Applications; // or import directly from writer-sdk/resources/applications/applications
 ```
 
-#### `writer-sdk/core`
+#### Refactor of `writer-sdk/core`, `error`, `pagination`, `resource`, `streaming` and `uploads`
 
-The `writer-sdk/core` file was intended to be internal-only but it was publicly accessible, as such it has been refactored and split up into internal files.
+Much of the `writer-sdk/core` file was intended to be internal-only but it was publicly accessible, as such it has been refactored and split up into internal and public files, with public-facing code moved to a new `core` folder and internal code moving to the private `internal` folder.
 
-If you were relying on anything that was only exported from `writer-sdk/core` and is also not accessible anywhere else, please open an issue and we'll consider adding it to the public API.
-
-#### `APIClient`
-
-The `APIClient` base client class has been removed as it is no longer needed. If you were importing this class then you must now import the main client class:
+At the same time, we moved some public-facing files which were previously at the top level into `core` to make the file structure cleaner and more clear:
 
 ```typescript
 // Before
-import { APIClient } from 'writer-sdk/core';
+import 'writer-sdk/error';
+import 'writer-sdk/pagination';
+import 'writer-sdk/resource';
+import 'writer-sdk/streaming';
+import 'writer-sdk/uploads';
 
 // After
-import { Writer } from 'writer-sdk';
+import 'writer-sdk/core/error';
+import 'writer-sdk/core/pagination';
+import 'writer-sdk/core/resource';
+import 'writer-sdk/core/streaming';
+import 'writer-sdk/core/uploads';
 ```
 
-#### Cleaned up `writer-sdk/uploads` exports
+If you were relying on anything that was only exported from `writer-sdk/core` and is also not accessible anywhere else, please open an issue and we'll consider adding it to the public API.
+
+#### Cleaned up `uploads` exports
 
-The following exports have been removed from `writer-sdk/uploads` as they were not intended to be a part of the public API:
+As part of the `core` refactor, `writer-sdk/uploads` was moved to `writer-sdk/core/uploads`
+and the following exports were removed, as they were not intended to be a part of the public API:
 
 - `fileFromPath`
 - `BlobPart`
@@ -347,5 +346,17 @@ The following exports have been removed from `writer-sdk/uploads` as they were n
 Note that `Uploadable` & `toFile` **are** still exported:
 
 ```typescript
-import { type Uploadable, toFile } from 'writer-sdk/uploads';
+import { type Uploadable, toFile } from 'writer-sdk/core/uploads';
+```
+
+#### `APIClient`
+
+The `APIClient` base client class has been removed as it is no longer needed. If you were importing this class then you must now import the main client class:
+
+```typescript
+// Before
+import { APIClient } from 'writer-sdk/core';
+
+// After
+import { Writer } from 'writer-sdk';
 ```

src/api-promise.ts

@@ -1,92 +1,2 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
-import { type Writer } from './client';
-
-import { type PromiseOrValue } from './internal/types';
-import { APIResponseProps, defaultParseResponse } from './internal/parse';
-
-/**
- * A subclass of `Promise` providing additional helper methods
- * for interacting with the SDK.
- */
-export class APIPromise<T> extends Promise<T> {
-  private parsedPromise: Promise<T> | undefined;
-  #client: Writer;
-
-  constructor(
-    client: Writer,
-    private responsePromise: Promise<APIResponseProps>,
-    private parseResponse: (
-      client: Writer,
-      props: APIResponseProps,
-    ) => PromiseOrValue<T> = defaultParseResponse,
-  ) {
-    super((resolve) => {
-      // this is maybe a bit weird but this has to be a no-op to not implicitly
-      // parse the response body; instead .then, .catch, .finally are overridden
-      // to parse the response
-      resolve(null as any);
-    });
-    this.#client = client;
-  }
-
-  _thenUnwrap<U>(transform: (data: T, props: APIResponseProps) => U): APIPromise<U> {
-    return new APIPromise(this.#client, this.responsePromise, async (client, props) =>
-      transform(await this.parseResponse(client, props), props),
-    );
-  }
-
-  /**
-   * Gets the raw `Response` instance instead of parsing the response
-   * data.
-   *
-   * If you want to parse the response body but still get the `Response`
-   * instance, you can use {@link withResponse()}.
-   *
-   * 👋 Getting the wrong TypeScript type for `Response`?
-   * Try setting `"moduleResolution": "NodeNext"` or add `"lib": ["DOM"]`
-   * to your `tsconfig.json`.
-   */
-  asResponse(): Promise<Response> {
-    return this.responsePromise.then((p) => p.response);
-  }
-
-  /**
-   * Gets the parsed response data and the raw `Response` instance.
-   *
-   * If you just want to get the raw `Response` instance without parsing it,
-   * you can use {@link asResponse()}.
-   *
-   * 👋 Getting the wrong TypeScript type for `Response`?
-   * Try setting `"moduleResolution": "NodeNext"` or add `"lib": ["DOM"]`
-   * to your `tsconfig.json`.
-   */
-  async withResponse(): Promise<{ data: T; response: Response }> {
-    const [data, response] = await Promise.all([this.parse(), this.asResponse()]);
-    return { data, response };
-  }
-
-  private parse(): Promise<T> {
-    if (!this.parsedPromise) {
-      this.parsedPromise = this.responsePromise.then((data) => this.parseResponse(this.#client, data));
-    }
-    return this.parsedPromise;
-  }
-
-  override then<TResult1 = T, TResult2 = never>(
-    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
-    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
-  ): Promise<TResult1 | TResult2> {
-    return this.parse().then(onfulfilled, onrejected);
-  }
-
-  override catch<TResult = never>(
-    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null,
-  ): Promise<T | TResult> {
-    return this.parse().catch(onrejected);
-  }
-
-  override finally(onfinally?: (() => void) | undefined | null): Promise<T> {
-    return this.parse().finally(onfinally);
-  }
-}
+/** @deprecated Import from ./core/api-promise instead */
+export * from './core/api-promise';

src/client.ts

@@ -13,18 +13,18 @@ import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
 import { VERSION } from './version';
-import * as Errors from './error';
-import * as Pagination from './pagination';
+import * as Errors from './core/error';
+import * as Pagination from './core/pagination';
 import {
   AbstractPage,
   type ApplicationJobsOffsetParams,
   ApplicationJobsOffsetResponse,
   type CursorPageParams,
   CursorPageResponse,
-} from './pagination';
-import * as Uploads from './uploads';
+} from './core/pagination';
+import * as Uploads from './core/uploads';
 import * as API from './resources/index';
-import { APIPromise } from './api-promise';
+import { APIPromise } from './core/api-promise';
 import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';

src/core/README.md

@@ -0,0 +1,3 @@
+# `core`
+
+This directory holds public modules implementing non-resource-specific SDK functionality.

src/core/api-promise.ts

@@ -0,0 +1,92 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { type Writer } from '../client';
+
+import { type PromiseOrValue } from '../internal/types';
+import { APIResponseProps, defaultParseResponse } from '../internal/parse';
+
+/**
+ * A subclass of `Promise` providing additional helper methods
+ * for interacting with the SDK.
+ */
+export class APIPromise<T> extends Promise<T> {
+  private parsedPromise: Promise<T> | undefined;
+  #client: Writer;
+
+  constructor(
+    client: Writer,
+    private responsePromise: Promise<APIResponseProps>,
+    private parseResponse: (
+      client: Writer,
+      props: APIResponseProps,
+    ) => PromiseOrValue<T> = defaultParseResponse,
+  ) {
+    super((resolve) => {
+      // this is maybe a bit weird but this has to be a no-op to not implicitly
+      // parse the response body; instead .then, .catch, .finally are overridden
+      // to parse the response
+      resolve(null as any);
+    });
+    this.#client = client;
+  }
+
+  _thenUnwrap<U>(transform: (data: T, props: APIResponseProps) => U): APIPromise<U> {
+    return new APIPromise(this.#client, this.responsePromise, async (client, props) =>
+      transform(await this.parseResponse(client, props), props),
+    );
+  }
+
+  /**
+   * Gets the raw `Response` instance instead of parsing the response
+   * data.
+   *
+   * If you want to parse the response body but still get the `Response`
+   * instance, you can use {@link withResponse()}.
+   *
+   * 👋 Getting the wrong TypeScript type for `Response`?
+   * Try setting `"moduleResolution": "NodeNext"` or add `"lib": ["DOM"]`
+   * to your `tsconfig.json`.
+   */
+  asResponse(): Promise<Response> {
+    return this.responsePromise.then((p) => p.response);
+  }
+
+  /**
+   * Gets the parsed response data and the raw `Response` instance.
+   *
+   * If you just want to get the raw `Response` instance without parsing it,
+   * you can use {@link asResponse()}.
+   *
+   * 👋 Getting the wrong TypeScript type for `Response`?
+   * Try setting `"moduleResolution": "NodeNext"` or add `"lib": ["DOM"]`
+   * to your `tsconfig.json`.
+   */
+  async withResponse(): Promise<{ data: T; response: Response }> {
+    const [data, response] = await Promise.all([this.parse(), this.asResponse()]);
+    return { data, response };
+  }
+
+  private parse(): Promise<T> {
+    if (!this.parsedPromise) {
+      this.parsedPromise = this.responsePromise.then((data) => this.parseResponse(this.#client, data));
+    }
+    return this.parsedPromise;
+  }
+
+  override then<TResult1 = T, TResult2 = never>(
+    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
+    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
+  ): Promise<TResult1 | TResult2> {
+    return this.parse().then(onfulfilled, onrejected);
+  }
+
+  override catch<TResult = never>(
+    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null,
+  ): Promise<T | TResult> {
+    return this.parse().catch(onrejected);
+  }
+
+  override finally(onfinally?: (() => void) | undefined | null): Promise<T> {
+    return this.parse().finally(onfinally);
+  }
+}