@deeptable/deeptable 0.1.0-alpha.1

package/src/internal/utils/path.ts

@@ -0,0 +1,88 @@
+import { DeepTableError } from '../../core/error';
+
+/**
+ * Percent-encode everything that isn't safe to have in a path without encoding safe chars.
+ *
+ * Taken from https://datatracker.ietf.org/doc/html/rfc3986#section-3.3:
+ * > unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
+ * > sub-delims  = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="
+ * > pchar       = unreserved / pct-encoded / sub-delims / ":" / "@"
+ */
+export function encodeURIPath(str: string) {
+  return str.replace(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/g, encodeURIComponent);
+}
+
+const EMPTY = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.create(null));
+
+export const createPathTagFunction = (pathEncoder = encodeURIPath) =>
+  function path(statics: readonly string[], ...params: readonly unknown[]): string {
+    // If there are no params, no processing is needed.
+    if (statics.length === 1) return statics[0]!;
+
+    let postPath = false;
+    const invalidSegments = [];
+    const path = statics.reduce((previousValue, currentValue, index) => {
+      if (/[?#]/.test(currentValue)) {
+        postPath = true;
+      }
+      const value = params[index];
+      let encoded = (postPath ? encodeURIComponent : pathEncoder)('' + value);
+      if (
+        index !== params.length &&
+        (value == null ||
+          (typeof value === 'object' &&
+            // handle values from other realms
+            value.toString ===
+              Object.getPrototypeOf(Object.getPrototypeOf((value as any).hasOwnProperty ?? EMPTY) ?? EMPTY)
+                ?.toString))
+      ) {
+        encoded = value + '';
+        invalidSegments.push({
+          start: previousValue.length + currentValue.length,
+          length: encoded.length,
+          error: `Value of type ${Object.prototype.toString
+            .call(value)
+            .slice(8, -1)} is not a valid path parameter`,
+        });
+      }
+      return previousValue + currentValue + (index === params.length ? '' : encoded);
+    }, '');
+
+    const pathOnly = path.split(/[?#]/, 1)[0]!;
+    const invalidSegmentPattern = /(?<=^|\/)(?:\.|%2e){1,2}(?=\/|$)/gi;
+    let match;
+
+    // Find all invalid segments
+    while ((match = invalidSegmentPattern.exec(pathOnly)) !== null) {
+      invalidSegments.push({
+        start: match.index,
+        length: match[0].length,
+        error: `Value "${match[0]}" can\'t be safely passed as a path parameter`,
+      });
+    }
+
+    invalidSegments.sort((a, b) => a.start - b.start);
+
+    if (invalidSegments.length > 0) {
+      let lastEnd = 0;
+      const underline = invalidSegments.reduce((acc, segment) => {
+        const spaces = ' '.repeat(segment.start - lastEnd);
+        const arrows = '^'.repeat(segment.length);
+        lastEnd = segment.start + segment.length;
+        return acc + spaces + arrows;
+      }, '');
+
+      throw new DeepTableError(
+        `Path parameters result in path with invalid segments:\n${invalidSegments
+          .map((e) => e.error)
+          .join('\n')}\n${path}\n${underline}`,
+      );
+    }
+
+    return path;
+  };
+
+/**
+ * URI-encodes path params and ensures no unsafe /./ or /../ path segments are introduced.
+ */
+export const path = /* @__PURE__ */ createPathTagFunction(encodeURIPath);

package/src/internal/utils/sleep.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));

package/src/internal/utils/uuid.ts

@@ -0,0 +1,17 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+/**
+ * https://stackoverflow.com/a/2117523
+ */
+export let uuid4 = function () {
+  const { crypto } = globalThis as any;
+  if (crypto?.randomUUID) {
+    uuid4 = crypto.randomUUID.bind(crypto);
+    return crypto.randomUUID();
+  }
+  const u8 = new Uint8Array(1);
+  const randomByte = crypto ? () => crypto.getRandomValues(u8)[0]! : () => (Math.random() * 0xff) & 0xff;
+  return '10000000-1000-4000-8000-100000000000'.replace(/[018]/g, (c) =>
+    (+c ^ (randomByte() & (15 >> (+c / 4)))).toString(16),
+  );
+};

package/src/internal/utils/values.ts

@@ -0,0 +1,105 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { DeepTableError } from '../../core/error';
+
+// https://url.spec.whatwg.org/#url-scheme-string
+const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
+
+export const isAbsoluteURL = (url: string): boolean => {
+  return startsWithSchemeRegexp.test(url);
+};
+
+export let isArray = (val: unknown): val is unknown[] => ((isArray = Array.isArray), isArray(val));
+export let isReadonlyArray = isArray as (val: unknown) => val is readonly unknown[];
+
+/** Returns an object if the given value isn't an object, otherwise returns as-is */
+export function maybeObj(x: unknown): object {
+  if (typeof x !== 'object') {
+    return {};
+  }
+
+  return x ?? {};
+}
+
+// https://stackoverflow.com/a/34491287
+export function isEmptyObj(obj: Object | null | undefined): boolean {
+  if (!obj) return true;
+  for (const _k in obj) return false;
+  return true;
+}
+
+// https://eslint.org/docs/latest/rules/no-prototype-builtins
+export function hasOwn<T extends object = object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+export const ensurePresent = <T>(value: T | null | undefined): T => {
+  if (value == null) {
+    throw new DeepTableError(`Expected a value to be given but received ${value} instead.`);
+  }
+
+  return value;
+};
+
+export const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
+    throw new DeepTableError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new DeepTableError(`${name} must be a positive integer`);
+  }
+  return n;
+};
+
+export const coerceInteger = (value: unknown): number => {
+  if (typeof value === 'number') return Math.round(value);
+  if (typeof value === 'string') return parseInt(value, 10);
+
+  throw new DeepTableError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceFloat = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return parseFloat(value);
+
+  throw new DeepTableError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceBoolean = (value: unknown): boolean => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value === 'true';
+  return Boolean(value);
+};
+
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
+export const safeJSON = (text: string) => {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+};

package/src/internal/utils.ts

@@ -0,0 +1,8 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './utils/values';
+export * from './utils/base64';
+export * from './utils/env';
+export * from './utils/log';
+export * from './utils/uuid';
+export * from './utils/sleep';

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';

package/src/resource.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/resource instead */
+export * from './core/resource';

package/src/resources/files.ts

@@ -0,0 +1,138 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../core/pagination';
+import { type Uploadable } from '../core/uploads';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { multipartFormRequestOptions } from '../internal/uploads';
+import { path } from '../internal/utils/path';
+
+export class Files extends APIResource {
+  /**
+   * Get metadata for a specific file.
+   *
+   * @example
+   * ```ts
+   * const file = await client.files.retrieve(
+   *   'file_01abc2def3ghjkmnpqrs4uvwxy',
+   * );
+   * ```
+   */
+  retrieve(fileID: string, options?: RequestOptions): APIPromise<File> {
+    return this._client.get(path`/v1/files/${fileID}`, options);
+  }
+
+  /**
+   * List all files uploaded by the current user.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const file of client.files.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: FileListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<FilesCursorIDPage, File> {
+    return this._client.getAPIList('/v1/files', CursorIDPage<File>, { query, ...options });
+  }
+
+  /**
+   * Delete a file. This cannot be undone.
+   *
+   * @example
+   * ```ts
+   * await client.files.delete(
+   *   'file_01abc2def3ghjkmnpqrs4uvwxy',
+   * );
+   * ```
+   */
+  delete(fileID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/files/${fileID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Upload an Excel spreadsheet file for later processing.
+   *
+   * Supported formats:
+   *
+   * - Excel (.xlsx)
+   *
+   * Maximum file size: 100 MB
+   *
+   * @example
+   * ```ts
+   * const file = await client.files.upload({
+   *   file: fs.createReadStream('path/to/file'),
+   * });
+   * ```
+   */
+  upload(body: FileUploadParams, options?: RequestOptions): APIPromise<File> {
+    return this._client.post('/v1/files', multipartFormRequestOptions({ body, ...options }, this._client));
+  }
+}
+
+export type FilesCursorIDPage = CursorIDPage<File>;
+
+/**
+ * Response representing an uploaded file.
+ *
+ * This is returned from POST (upload), GET (retrieve), and list endpoints.
+ */
+export interface File {
+  /**
+   * The unique identifier for this file.
+   */
+  id: string;
+
+  /**
+   * The MIME type of the file.
+   */
+  content_type: string;
+
+  /**
+   * The timestamp when the file was uploaded.
+   */
+  created_at: string;
+
+  /**
+   * The original filename of the uploaded file.
+   */
+  file_name: string;
+
+  /**
+   * The size of the file in bytes.
+   */
+  size: number;
+
+  /**
+   * The object type, which is always 'file'.
+   */
+  object?: 'file';
+}
+
+export interface FileListParams extends CursorIDPageParams {}
+
+export interface FileUploadParams {
+  /**
+   * The spreadsheet file to upload
+   */
+  file: Uploadable;
+}
+
+export declare namespace Files {
+  export {
+    type File as File,
+    type FilesCursorIDPage as FilesCursorIDPage,
+    type FileListParams as FileListParams,
+    type FileUploadParams as FileUploadParams,
+  };
+}

package/src/resources/index.ts

@@ -0,0 +1,16 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Files,
+  type File,
+  type FileListParams,
+  type FileUploadParams,
+  type FilesCursorIDPage,
+} from './files';
+export {
+  StructuredSheets,
+  type StructuredSheetResponse,
+  type StructuredSheetCreateParams,
+  type StructuredSheetListParams,
+  type StructuredSheetResponsesCursorIDPage,
+} from './structured-sheets/structured-sheets';

package/src/resources/structured-sheets/exports.ts

@@ -0,0 +1,32 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Exports extends APIResource {
+  /**
+   * Download the structured data as a SQLite database file. Only available when
+   * conversion status is 'completed'.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.structuredSheets.exports.downloadSqlite(
+   *     'ss_01abc2def3ghjkmnpqrs4uvwxy',
+   *   );
+   *
+   * const content = await response.blob();
+   * console.log(content);
+   * ```
+   */
+  downloadSqlite(structuredSheetsID: string, options?: RequestOptions): APIPromise<Response> {
+    return this._client.get(path`/v1/structured-sheets/${structuredSheetsID}/exports/sqlite`, {
+      ...options,
+      headers: buildHeaders([{ Accept: 'application/x-sqlite3' }, options?.headers]),
+      __binaryResponse: true,
+    });
+  }
+}

package/src/resources/structured-sheets/index.ts

@@ -0,0 +1,10 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Exports } from './exports';
+export {
+  StructuredSheets,
+  type StructuredSheetResponse,
+  type StructuredSheetCreateParams,
+  type StructuredSheetListParams,
+  type StructuredSheetResponsesCursorIDPage,
+} from './structured-sheets';

package/src/resources/structured-sheets/structured-sheets.ts

@@ -0,0 +1,184 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as ExportsAPI from './exports';
+import { Exports } from './exports';
+import { APIPromise } from '../../core/api-promise';
+import { CursorIDPage, type CursorIDPageParams, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class StructuredSheets extends APIResource {
+  exports: ExportsAPI.Exports = new ExportsAPI.Exports(this._client);
+
+  /**
+   * Start converting a spreadsheet workbook into structured data. This initiates an
+   * asynchronous conversion process. Poll the returned resource using the `id` to
+   * check completion status.
+   *
+   * @example
+   * ```ts
+   * const structuredSheetResponse =
+   *   await client.structuredSheets.create({
+   *     file_id: 'file_01h45ytscbebyvny4gc8cr8ma2',
+   *   });
+   * ```
+   */
+  create(body: StructuredSheetCreateParams, options?: RequestOptions): APIPromise<StructuredSheetResponse> {
+    return this._client.post('/v1/structured-sheets', { body, ...options });
+  }
+
+  /**
+   * Get the status and details of a structured sheets conversion.
+   *
+   * @example
+   * ```ts
+   * const structuredSheetResponse =
+   *   await client.structuredSheets.retrieve(
+   *     'ss_01abc2def3ghjkmnpqrs4uvwxy',
+   *   );
+   * ```
+   */
+  retrieve(structuredSheetsID: string, options?: RequestOptions): APIPromise<StructuredSheetResponse> {
+    return this._client.get(path`/v1/structured-sheets/${structuredSheetsID}`, options);
+  }
+
+  /**
+   * List all structured sheets conversions for the authenticated user. Results are
+   * paginated using cursor-based pagination.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const structuredSheetResponse of client.structuredSheets.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: StructuredSheetListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<StructuredSheetResponsesCursorIDPage, StructuredSheetResponse> {
+    return this._client.getAPIList('/v1/structured-sheets', CursorIDPage<StructuredSheetResponse>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Delete a structured sheets conversion and its associated exports. This action
+   * cannot be undone.
+   *
+   * @example
+   * ```ts
+   * await client.structuredSheets.delete(
+   *   'ss_01abc2def3ghjkmnpqrs4uvwxy',
+   * );
+   * ```
+   */
+  delete(structuredSheetsID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/structured-sheets/${structuredSheetsID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type StructuredSheetResponsesCursorIDPage = CursorIDPage<StructuredSheetResponse>;
+
+/**
+ * Response representing a structured sheets conversion job.
+ *
+ * This is returned from POST (create), GET (retrieve), and list endpoints.
+ */
+export interface StructuredSheetResponse {
+  /**
+   * The unique identifier for this structured sheets conversion.
+   */
+  id: string;
+
+  /**
+   * The timestamp when the conversion was started.
+   */
+  created_at: string;
+
+  /**
+   * The unique identifier for the source file.
+   */
+  file_id: string;
+
+  /**
+   * The current processing status.
+   */
+  status: 'pending' | 'queued' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
+
+  /**
+   * The timestamp when the conversion was last updated.
+   */
+  updated_at: string;
+
+  /**
+   * List of export formats available for download (e.g., ['sqlite']).
+   */
+  exports_available?: Array<string>;
+
+  /**
+   * Error information when processing fails.
+   */
+  last_error?: StructuredSheetResponse.LastError | null;
+
+  /**
+   * The object type, which is always 'structured_sheet'.
+   */
+  object?: 'structured_sheet';
+
+  /**
+   * List of sheet names included in this conversion.
+   */
+  sheet_names?: Array<string>;
+}
+
+export namespace StructuredSheetResponse {
+  /**
+   * Error information when processing fails.
+   */
+  export interface LastError {
+    /**
+     * A machine-readable error code.
+     */
+    code: string;
+
+    /**
+     * A human-readable description of the error.
+     */
+    message: string;
+  }
+}
+
+export interface StructuredSheetCreateParams {
+  /**
+   * The unique identifier of the file to convert.
+   */
+  file_id: string;
+
+  /**
+   * List of sheet names to convert. If None, all sheets will be converted.
+   */
+  sheet_names?: Array<string> | null;
+}
+
+export interface StructuredSheetListParams extends CursorIDPageParams {}
+
+StructuredSheets.Exports = Exports;
+
+export declare namespace StructuredSheets {
+  export {
+    type StructuredSheetResponse as StructuredSheetResponse,
+    type StructuredSheetResponsesCursorIDPage as StructuredSheetResponsesCursorIDPage,
+    type StructuredSheetCreateParams as StructuredSheetCreateParams,
+    type StructuredSheetListParams as StructuredSheetListParams,
+  };
+
+  export { Exports as Exports };
+}

package/src/resources/structured-sheets.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './structured-sheets/index';

package/src/resources.ts

@@ -0,0 +1 @@
+export * from './resources/index';

package/src/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  // this config is included in the published src directory to prevent TS errors
+  // from appearing when users go to source, and VSCode opens the source .ts file
+  // via declaration maps
+  "include": ["index.ts"],
+  "compilerOptions": {
+    "target": "ES2015",
+    "lib": ["DOM", "DOM.Iterable", "ES2018"],
+    "moduleResolution": "node"
+  }
+}

package/src/uploads.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/uploads instead */
+export * from './core/uploads';

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = '0.1.0-alpha.1'; // x-release-please-version

package/uploads.d.mts

@@ -0,0 +1,2 @@
+export * from "./core/uploads.mjs";
+//# sourceMappingURL=uploads.d.mts.map

package/uploads.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.d.mts","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":""}

package/uploads.d.ts

@@ -0,0 +1,2 @@
+export * from "./core/uploads.js";
+//# sourceMappingURL=uploads.d.ts.map

package/uploads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":""}

package/uploads.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("./internal/tslib.js");
+/** @deprecated Import from ./core/uploads instead */
+tslib_1.__exportStar(require("./core/uploads.js"), exports);
+//# sourceMappingURL=uploads.js.map

package/uploads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.js","sourceRoot":"","sources":["src/uploads.ts"],"names":[],"mappings":";;;AAAA,qDAAqD;AACrD,4DAA+B"}

package/uploads.mjs

@@ -0,0 +1,2 @@
+export * from "./core/uploads.mjs";
+//# sourceMappingURL=uploads.mjs.map