feat(client): add support for accessing the raw response object (#105)

README.md

@@ -263,6 +263,32 @@ On timeout, an `APIConnectionTimeoutError` is thrown.
 
 Note that requests which time out will be [retried twice by default](#retries).
 
+## Advanced Usage
+
+### Accessing raw Response data (e.g., headers)
+
+The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
+
+You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
+
+```ts
+const anthropic = new Anthropic();
+
+const response = await anthropic.completions
+  .create({
+    prompt: `${Anthropic.HUMAN_PROMPT} Can you help me effectively ask for a raise at work? ${Anthropic.AI_PROMPT}`,
+    max_tokens_to_sample: 300,
+    model: 'claude-2',
+  })
+  .asResponse();
+console.log(response.headers.get('X-My-Header'));
+console.log(response.raw.statusText); // access the underlying Response object
+
+// parses the response body, returning an object if the API responds with JSON
+const completion: Completions.Completion = await response.parse();
+console.log(completion.completion);
+```
+
 ## Configuring an HTTP(S) Agent (e.g., for proxies)
 
 By default, this library uses a stable agent for all http/https requests to reuse TCP connections, eliminating many TCP & TLS handshakes and shaving around 100ms off most requests.

jest.config.js

@@ -7,5 +7,5 @@ module.exports = {
     '^@anthropic-ai/sdk/_shims/(.*)$': '<rootDir>/src/_shims/$1.node',
     '^@anthropic-ai/sdk/(.*)$': '<rootDir>/src/$1',
   },
-  modulePathIgnorePatterns: ['<rootDir>/ecosystem-tests/', '<rootDir>/dist/'],
+  modulePathIgnorePatterns: ['<rootDir>/ecosystem-tests/', '<rootDir>/dist/', '<rootDir>/deno_tests/'],
 };

package.json

@@ -95,7 +95,7 @@
     "ts-node": "^10.5.0",
     "tsc-alias": "^1.8.6",
     "tsc-multi": "^1.1.0",
-    "tsconfig-paths": "^3.12.0",
+    "tsconfig-paths": "^4.0.0",
     "typescript": "^4.8.2"
   }
 }

src/_shims/ReadableStream.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+/**
+ * >>> Confused? <<<
+ *
+ * If you're getting errors from these types, try adding "lib": ["DOM"]
+ * to your tsconfig.json, or otherwise configure the appropriate builtin
+ * `ReadableStream` type for your environment.
+ */
+
+// @ts-ignore
+type _ReadableStream<R = any> = unknown extends ReadableStream ? never : ReadableStream<R>;
+declare const _ReadableStream: {
+  prototype: _ReadableStream;
+  new (
+    underlyingSource: _UnderlyingByteSource,
+    strategy?: { highWaterMark?: number },
+  ): _ReadableStream<Uint8Array>;
+  new <R = any>(
+    underlyingSource: _UnderlyingDefaultSource<R>,
+    strategy?: _QueuingStrategy<R>,
+  ): _ReadableStream<R>;
+  new <R = any>(underlyingSource?: _UnderlyingSource<R>, strategy?: _QueuingStrategy<R>): _ReadableStream<R>;
+};
+
+// @ts-ignore
+type _UnderlyingSource<R = any> = unknown extends UnderlyingSource ? never : UnderlyingSource<R>;
+// @ts-ignore
+type _UnderlyingByteSource = unknown extends UnderlyingByteSource ? never : UnderlyingByteSource;
+type _UnderlyingDefaultSource<R = any> =
+  // @ts-ignore
+  unknown extends UnderlyingDefaultSource ? never : UnderlyingDefaultSource<R>;
+// @ts-ignore
+type _QueuingStrategy<R = any> = unknown extends QueuingStrategy ? never : QueuingStrategy<R>;
+
+export { _ReadableStream as ReadableStream };

src/_shims/ReadableStream.js

@@ -0,0 +1,5 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+exports.ReadableStream = ReadableStream;

src/_shims/ReadableStream.mjs

@@ -0,0 +1,7 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+
+const _ReadableStream = ReadableStream;
+
+export { _ReadableStream as ReadableStream };

src/_shims/ReadableStream.node.ts

@@ -0,0 +1,6 @@
+/**
+ * Disclaimer: modules in _shims aren't intended to be imported by SDK users.
+ */
+import { ReadableStream } from 'web-streams-polyfill';
+
+export { ReadableStream };

src/_shims/fetch.d.ts

@@ -26,6 +26,8 @@ type _Response = unknown extends Response ? never : Response;
 // @ts-ignore
 type _ResponseInit = unknown extends ResponseInit ? never : ResponseInit;
 // @ts-ignore
+type _ResponseType = unknown extends ResponseType ? never : ResponseType;
+// @ts-ignore
 type _BodyInit = unknown extends BodyInit ? never : BodyInit;
 // @ts-ignore
 type _Headers = unknown extends Headers ? never : Headers;
@@ -49,4 +51,9 @@ declare const _Headers: {
 export const isPolyfilled = false;
 
 export { _fetch as fetch, _Request as Request, _Response as Response, _Headers as Headers };
-export type { _RequestInit as RequestInit, _RequestInfo as RequestInfo, _BodyInit as BodyInit };
+export type {
+  _RequestInit as RequestInit,
+  _RequestInfo as RequestInfo,
+  _ResponseType as ResponseType,
+  _BodyInit as BodyInit,
+};

src/_shims/fetch.node.d.ts

@@ -26,6 +26,11 @@ type _RequestInit = unknown extends RequestInit ? nf.RequestInit : RequestInit;
 type _Response = unknown extends Response ? nf.Response : Response;
 // @ts-ignore
 type _ResponseInit = unknown extends ResponseInit ? nf.ResponseInit : ResponseInit;
+type _ResponseType =
+  // @ts-ignore
+  unknown extends ResponseType ? 'basic' | 'cors' | 'default' | 'error' | 'opaque' | 'opaqueredirect'
+  : // @ts-ignore
+    ResponseType;
 // @ts-ignore
 type _BodyInit = unknown extends BodyInit ? nf.BodyInit : BodyInit;
 // @ts-ignore
@@ -50,4 +55,9 @@ declare const _Headers: {
 export const isPolyfilled = false;
 
 export { _fetch as fetch, _Request as Request, _Response as Response, _Headers as Headers };
-export type { _RequestInit as RequestInit, _RequestInfo as RequestInfo, _BodyInit as BodyInit };
+export type {
+  _RequestInit as RequestInit,
+  _RequestInfo as RequestInfo,
+  _ResponseType as ResponseType,
+  _BodyInit as BodyInit,
+};