feat(api): update via SDK Studio (#15)

Author: stainless-app[bot]

.stats.yml

@@ -1,2 +1,2 @@
-configured_endpoints: 3
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/grid%2Fspreadsheet-api-4f7e4249cd44e912120dd6531cc506a8c0c0e3e3b5f0c91b18c37177b850b590.yml
+configured_endpoints: 5
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/grid%2Fspreadsheet-api-cf876af98da268e94e99a8b5e9b92deb5ce68bf70db902e211d89c8eda5eecf1.yml

README.md

@@ -53,6 +53,50 @@ main();
 
 Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
 
+## File uploads
+
+Request parameters that correspond to file uploads can be passed in many different forms:
+
+- `File` (or an object with the same structure)
+- a `fetch` `Response` (or an object with the same structure)
+- an `fs.ReadStream`
+- the return value of our `toFile` helper
+
+```ts
+import fs from 'fs';
+import Grid, { toFile } from '@grid-is/api';
+
+const client = new Grid();
+
+// If you have access to Node `fs` we recommend using `fs.createReadStream()`:
+await client.workbooks.upload({
+  body: fs.createReadStream('/path/to/file'),
+  'X-Uploaded-Filename': 'X-Uploaded-Filename',
+});
+
+// Or if you have the web `File` API you can pass a `File` instance:
+await client.workbooks.upload({
+  body: new File(['my bytes'], 'file'),
+  'X-Uploaded-Filename': 'X-Uploaded-Filename',
+});
+
+// You can also pass a `fetch` `Response`:
+await client.workbooks.upload({
+  body: await fetch('https://somesite/file'),
+  'X-Uploaded-Filename': 'X-Uploaded-Filename',
+});
+
+// Finally, if none of the above are convenient, you can use our `toFile` helper:
+await client.workbooks.upload({
+  body: await toFile(Buffer.from('my bytes'), 'file'),
+  'X-Uploaded-Filename': 'X-Uploaded-Filename',
+});
+await client.workbooks.upload({
+  body: await toFile(new Uint8Array([0, 1, 2]), 'file'),
+  'X-Uploaded-Filename': 'X-Uploaded-Filename',
+});
+```
+
 ## Handling errors
 
 When the library is unable to connect to the API,

api.md

@@ -2,10 +2,14 @@
 
 Types:
 
+- <code><a href="./src/resources/workbooks.ts">WorkbookListResponse</a></code>
 - <code><a href="./src/resources/workbooks.ts">WorkbookQueryResponse</a></code>
+- <code><a href="./src/resources/workbooks.ts">WorkbookUploadResponse</a></code>
 
 Methods:
 
+- <code title="get /v1/workbooks">client.workbooks.<a href="./src/resources/workbooks.ts">list</a>({ ...params }) -> WorkbookListResponse</code>
 - <code title="post /v1/workbooks/{id}/export">client.workbooks.<a href="./src/resources/workbooks.ts">export</a>(id, { ...params }) -> Response</code>
 - <code title="post /v1/workbooks/{id}/query">client.workbooks.<a href="./src/resources/workbooks.ts">query</a>(id, { ...params }) -> WorkbookQueryResponse</code>
 - <code title="post /v1/workbooks/{id}/chart">client.workbooks.<a href="./src/resources/workbooks.ts">renderChart</a>(id, { ...params }) -> Response</code>
+- <code title="post /v1/workbooks">client.workbooks.<a href="./src/resources/workbooks.ts">upload</a>({ ...params }) -> WorkbookUploadResponse</code>

src/client.ts

@@ -20,9 +20,13 @@ import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
 import {
   WorkbookExportParams,
+  WorkbookListParams,
+  WorkbookListResponse,
   WorkbookQueryParams,
   WorkbookQueryResponse,
   WorkbookRenderChartParams,
+  WorkbookUploadParams,
+  WorkbookUploadResponse,
   Workbooks,
 } from './resources/workbooks';
 import { readEnv } from './internal/utils/env';
@@ -731,9 +735,13 @@ export declare namespace Grid {
 
   export {
     Workbooks as Workbooks,
+    type WorkbookListResponse as WorkbookListResponse,
     type WorkbookQueryResponse as WorkbookQueryResponse,
+    type WorkbookUploadResponse as WorkbookUploadResponse,
+    type WorkbookListParams as WorkbookListParams,
     type WorkbookExportParams as WorkbookExportParams,
     type WorkbookQueryParams as WorkbookQueryParams,
     type WorkbookRenderChartParams as WorkbookRenderChartParams,
+    type WorkbookUploadParams as WorkbookUploadParams,
   };
 }

src/resources/index.ts

@@ -2,8 +2,12 @@
 
 export {
   Workbooks,
+  type WorkbookListResponse,
   type WorkbookQueryResponse,
+  type WorkbookUploadResponse,
+  type WorkbookListParams,
   type WorkbookExportParams,
   type WorkbookQueryParams,
   type WorkbookRenderChartParams,
+  type WorkbookUploadParams,
 } from './workbooks';

src/resources/workbooks.ts

@@ -7,6 +7,18 @@ import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
 export class Workbooks extends APIResource {
+  /**
+   * List the workbooks linked to an account.
+   *
+   * This endpoint returns a paginated list of workbooks.
+   */
+  list(
+    query: WorkbookListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<WorkbookListResponse> {
+    return this._client.get('/v1/workbooks', { query, ...options });
+  }
+
   /**
    * Export a workbook as an .xlsx file. Cells can be updated before the workbook is
    * exported.
@@ -44,6 +56,88 @@ export class Workbooks extends APIResource {
       __binaryResponse: true,
     });
   }
+
+  /**
+   * Upload an Excel workbook file and make it available in the API.
+   *
+   * The workbook will be processed in the background. Once it's processed
+   * successfully it will be available for querying and exporting.
+   */
+  upload(params: WorkbookUploadParams, options?: RequestOptions): APIPromise<WorkbookUploadResponse> {
+    const { body, 'X-Uploaded-Filename': xUploadedFilename } = params;
+    return this._client.post('/v1/workbooks', {
+      body: body,
+      ...options,
+      headers: buildHeaders([
+        { 'Content-Type': 'application/octet-stream', 'X-Uploaded-Filename': xUploadedFilename },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export interface WorkbookListResponse {
+  items: Array<WorkbookListResponse.Item>;
+
+  pagination: WorkbookListResponse.Pagination;
+}
+
+export namespace WorkbookListResponse {
+  export interface Item {
+    /**
+     * A workbook's unique identifier
+     */
+    id: string;
+
+    /**
+     * The date/time the workbook was created
+     */
+    created: string;
+
+    /**
+     * The defect that was found in the most recent version of the workbook, if any
+     */
+    defect:
+      | ''
+      | 'too_big'
+      | 'converted_workbook_too_big'
+      | 'unrecognized_format'
+      | 'cannot_fetch_from_remote'
+      | 'processing_timeout'
+      | 'conversion_error';
+
+    /**
+     * The original filename of the uploaded workbook
+     */
+    filename: string;
+
+    /**
+     * The date/time the workbook was last modified
+     */
+    modified: string;
+
+    /**
+     * The current state of the most recent version of the workbook
+     */
+    state: 'processing' | 'ready' | 'error';
+
+    /**
+     * The most recent version of the workbook
+     */
+    version: number;
+
+    /**
+     * The latest version of the workbook that has a 'ready' state
+     */
+    latest_ready_version?: number | null;
+  }
+
+  export interface Pagination {
+    /**
+     * The cursor to pass on as query parameter for the next batch of items, if any
+     */
+    next_cursor?: string | null;
+  }
 }
 
 /**
@@ -393,6 +487,26 @@ export namespace WorkbookQueryResponse {
   }
 }
 
+export interface WorkbookUploadResponse {
+  /**
+   * The id of the newly uploaded workbook
+   */
+  id: string;
+}
+
+export interface WorkbookListParams {
+  /**
+   * Cursor for the next page of items. If not provided, the first batch of items
+   * will be returned.
+   */
+  cursor?: string;
+
+  /**
+   * Number of items to return per page
+   */
+  limit?: number;
+}
+
 export interface WorkbookExportParams {
   /**
    * Cells to update before exporting
@@ -611,11 +725,27 @@ export namespace WorkbookRenderChartParams {
   }
 }
 
+export interface WorkbookUploadParams {
+  /**
+   * Body param:
+   */
+  body: string | ArrayBuffer | ArrayBufferView | Blob | DataView;
+
+  /**
+   * Header param: The name of the workbook file
+   */
+  'X-Uploaded-Filename': string;
+}
+
 export declare namespace Workbooks {
   export {
+    type WorkbookListResponse as WorkbookListResponse,
     type WorkbookQueryResponse as WorkbookQueryResponse,
+    type WorkbookUploadResponse as WorkbookUploadResponse,
+    type WorkbookListParams as WorkbookListParams,
     type WorkbookExportParams as WorkbookExportParams,
     type WorkbookQueryParams as WorkbookQueryParams,
     type WorkbookRenderChartParams as WorkbookRenderChartParams,
+    type WorkbookUploadParams as WorkbookUploadParams,
   };
 }

tests/api-resources/workbooks.test.ts

@@ -1,13 +1,33 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import Grid from '@grid-is/api';
+import Grid, { toFile } from '@grid-is/api';
 
 const client = new Grid({
   bearerToken: 'My Bearer Token',
   baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010',
 });
 
 describe('resource workbooks', () => {
+  // skipped: tests are disabled for the time being
+  test.skip('list', async () => {
+    const responsePromise = client.workbooks.list();
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  // skipped: tests are disabled for the time being
+  test.skip('list: request options and params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(
+      client.workbooks.list({ cursor: 'cursor', limit: 0 }, { path: '/_stainless_unknown_path' }),
+    ).rejects.toThrow(Grid.NotFoundError);
+  });
+
   // skipped: tests are disabled for the time being
   test.skip('query: only required params', async () => {
     const responsePromise = client.workbooks.query('id', { read: ['A1', 'Sheet2!B3', '=SUM(A1:A4)'] });
@@ -37,4 +57,27 @@ describe('resource workbooks', () => {
       apply: [{ target: 'A2', value: 1234 }],
     });
   });
+
+  // skipped: tests are disabled for the time being
+  test.skip('upload: only required params', async () => {
+    const responsePromise = client.workbooks.upload({
+      body: await toFile(Buffer.from('# my file contents'), 'README.md'),
+      'X-Uploaded-Filename': 'X-Uploaded-Filename',
+    });
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  // skipped: tests are disabled for the time being
+  test.skip('upload: required and optional params', async () => {
+    const response = await client.workbooks.upload({
+      body: await toFile(Buffer.from('# my file contents'), 'README.md'),
+      'X-Uploaded-Filename': 'X-Uploaded-Filename',
+    });
+  });
 });