@valtown/sdk 2.1.0 → 3.1.0

package/src/internal/utils/path.ts

@@ -0,0 +1,88 @@
+import { ValTownError } 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 ValTownError(
+        `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 { ValTownError } 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 ValTownError(`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 ValTownError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new ValTownError(`${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 ValTownError(`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 ValTownError(`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/pagination.ts

@@ -1,123 +1,2 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
-import { AbstractPage, Response, APIClient, FinalRequestOptions, PageInfo } from './core';
-
-export interface PageCursorURLResponse<Item> {
-  data: Array<Item>;
-
-  links: PageCursorURLResponse.Links;
-}
-
-export namespace PageCursorURLResponse {
-  export interface Links {
-    next?: string;
-
-    prev?: string;
-  }
-}
-
-export interface PageCursorURLParams {
-  limit?: number;
-
-  offset?: number;
-}
-
-export class PageCursorURL<Item> extends AbstractPage<Item> implements PageCursorURLResponse<Item> {
-  data: Array<Item>;
-
-  links: PageCursorURLResponse.Links;
-
-  constructor(
-    client: APIClient,
-    response: Response,
-    body: PageCursorURLResponse<Item>,
-    options: FinalRequestOptions,
-  ) {
-    super(client, response, body, options);
-
-    this.data = body.data || [];
-    this.links = body.links || {};
-  }
-
-  getPaginatedItems(): Item[] {
-    return this.data ?? [];
-  }
-
-  // @deprecated Please use `nextPageInfo()` instead
-  nextPageParams(): Partial<PageCursorURLParams> | null {
-    const info = this.nextPageInfo();
-    if (!info) return null;
-    if ('params' in info) return info.params;
-    const params = Object.fromEntries(info.url.searchParams);
-    if (!Object.keys(params).length) return null;
-    return params;
-  }
-
-  nextPageInfo(): PageInfo | null {
-    const url = this.links?.next;
-    if (!url) return null;
-
-    return { url: new URL(url) };
-  }
-}
-
-export interface CursorResponse<Item> {
-  data: Array<Item>;
-
-  links: CursorResponse.Links;
-}
-
-export namespace CursorResponse {
-  export interface Links {
-    next?: string;
-  }
-}
-
-export interface CursorParams {
-  cursor?: string;
-}
-
-export class Cursor<Item> extends AbstractPage<Item> implements CursorResponse<Item> {
-  data: Array<Item>;
-
-  links: CursorResponse.Links;
-
-  constructor(
-    client: APIClient,
-    response: Response,
-    body: CursorResponse<Item>,
-    options: FinalRequestOptions,
-  ) {
-    super(client, response, body, options);
-
-    this.data = body.data || [];
-    this.links = body.links || {};
-  }
-
-  getPaginatedItems(): Item[] {
-    return this.data ?? [];
-  }
-
-  // @deprecated Please use `nextPageInfo()` instead
-  nextPageParams(): Partial<CursorParams> | null {
-    const info = this.nextPageInfo();
-    if (!info) return null;
-    if ('params' in info) return info.params;
-    const params = Object.fromEntries(info.url.searchParams);
-    if (!Object.keys(params).length) return null;
-    return params;
-  }
-
-  nextPageInfo(): PageInfo | null {
-    const cursor = this.links?.next;
-    if (!cursor) {
-      return null;
-    }
-
-    return {
-      params: {
-        cursor,
-      },
-    };
-  }
-}
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';

package/src/resource.ts

@@ -1,11 +1,2 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-
-import type { ValTown } from './index';
-
-export abstract class APIResource {
-  protected _client: ValTown;
-
-  constructor(client: ValTown) {
-    this._client = client;
-  }
-}
+/** @deprecated Import from ./core/resource instead */
+export * from './core/resource';

package/src/resources/alias/alias.ts

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../resource';
+import { APIResource } from '../../core/resource';
 import * as UsernameAPI from './username/username';
 import { Username } from './username/username';
 

package/src/resources/alias/username/index.ts

@@ -1,4 +1,4 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 export { Username } from './username';
-export { ValName } from './val-name';
+export { ValName, type ValNameRetrieveParams } from './val-name';

package/src/resources/alias/username/username.ts

@@ -1,10 +1,12 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../../resource';
-import * as Core from '../../../core';
+import { APIResource } from '../../../core/resource';
 import * as Shared from '../../shared';
 import * as ValNameAPI from './val-name';
-import { ValName } from './val-name';
+import { ValName, ValNameRetrieveParams } from './val-name';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
 
 export class Username extends APIResource {
   valName: ValNameAPI.ValName = new ValNameAPI.ValName(this._client);
@@ -19,13 +21,13 @@ export class Username extends APIResource {
    * );
    * ```
    */
-  retrieve(username: string, options?: Core.RequestOptions): Core.APIPromise<Shared.User> {
-    return this._client.get(`/v1/alias/${username}`, options);
+  retrieve(username: string, options?: RequestOptions): APIPromise<Shared.User> {
+    return this._client.get(path`/v1/alias/${username}`, options);
   }
 }
 
 Username.ValName = ValName;
 
 export declare namespace Username {
-  export { ValName as ValName };
+  export { ValName as ValName, type ValNameRetrieveParams as ValNameRetrieveParams };
 }

package/src/resources/alias/username/val-name.ts

@@ -1,8 +1,10 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../../resource';
-import * as Core from '../../../core';
+import { APIResource } from '../../../core/resource';
 import * as Shared from '../../shared';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
 
 export class ValName extends APIResource {
   /**
@@ -11,12 +13,24 @@ export class ValName extends APIResource {
    * @example
    * ```ts
    * const val = await client.alias.username.valName.retrieve(
-   *   'username',
    *   'val_name',
+   *   { username: 'username' },
    * );
    * ```
    */
-  retrieve(username: string, valName: string, options?: Core.RequestOptions): Core.APIPromise<Shared.Val> {
-    return this._client.get(`/v2/alias/vals/${username}/${valName}`, options);
+  retrieve(valName: string, params: ValNameRetrieveParams, options?: RequestOptions): APIPromise<Shared.Val> {
+    const { username } = params;
+    return this._client.get(path`/v2/alias/vals/${username}/${valName}`, options);
   }
 }
+
+export interface ValNameRetrieveParams {
+  /**
+   * Username of the user whose val you are looking for
+   */
+  username: string;
+}
+
+export declare namespace ValName {
+  export { type ValNameRetrieveParams as ValNameRetrieveParams };
+}

package/src/resources/blobs.ts

@@ -1,9 +1,11 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../resource';
-import { isRequestOptions } from '../core';
-import * as Core from '../core';
-import { type Response } from '../_shims/index';
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { type Uploadable } from '../core/uploads';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
 
 /**
  * Blob storage lets you store larger objects, including binary data
@@ -12,35 +14,30 @@ export class Blobs extends APIResource {
   /**
    * List blobs in your account
    */
-  list(query?: BlobListParams, options?: Core.RequestOptions): Core.APIPromise<BlobListResponse>;
-  list(options?: Core.RequestOptions): Core.APIPromise<BlobListResponse>;
   list(
-    query: BlobListParams | Core.RequestOptions = {},
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<BlobListResponse> {
-    if (isRequestOptions(query)) {
-      return this.list({}, query);
-    }
+    query: BlobListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<BlobListResponse> {
     return this._client.get('/v1/blob', { query, ...options });
   }
 
   /**
    * Delete a blob
    */
-  delete(key: string, options?: Core.RequestOptions): Core.APIPromise<void> {
-    return this._client.delete(`/v1/blob/${key}`, {
+  delete(key: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/blob/${key}`, {
       ...options,
-      headers: { Accept: '*/*', ...options?.headers },
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 
   /**
    * Get a blob’s contents.
    */
-  get(key: string, options?: Core.RequestOptions): Core.APIPromise<Response> {
-    return this._client.get(`/v1/blob/${key}`, {
+  get(key: string, options?: RequestOptions): APIPromise<Response> {
+    return this._client.get(path`/v1/blob/${key}`, {
       ...options,
-      headers: { Accept: 'application/octet-stream', ...options?.headers },
+      headers: buildHeaders([{ Accept: 'application/octet-stream' }, options?.headers]),
       __binaryResponse: true,
     });
   }
@@ -48,21 +45,16 @@ export class Blobs extends APIResource {
   /**
    * Store data in blob storage
    */
-  store(key: string, body?: BlobStoreParams, options?: Core.RequestOptions): Core.APIPromise<void>;
-  store(key: string, options?: Core.RequestOptions): Core.APIPromise<void>;
   store(
     key: string,
-    body?: BlobStoreParams | Core.RequestOptions,
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<void> {
-    if (isRequestOptions(body)) {
-      return this.store(key, undefined, body);
-    }
-    return this._client.post(`/v1/blob/${key}`, {
-      body,
+    params: BlobStoreParams | null | undefined = undefined,
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    const { blob } = params ?? {};
+    return this._client.post(path`/v1/blob/${key}`, {
+      body: blob,
       ...options,
-      headers: { Accept: '*/*', ...options?.headers },
-      __binaryRequest: true,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 }
@@ -95,7 +87,12 @@ export interface BlobListParams {
   prefix?: string;
 }
 
-export type BlobStoreParams = Core.Uploadable;
+export interface BlobStoreParams {
+  /**
+   * Binary input data
+   */
+  blob?: Uploadable;
+}
 
 export declare namespace Blobs {
   export {

package/src/resources/emails.ts

@@ -1,8 +1,8 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../resource';
-import { isRequestOptions } from '../core';
-import * as Core from '../core';
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
 
 /**
  * Val Town supports sending emails from vals
@@ -20,15 +20,10 @@ export class Emails extends APIResource {
    * });
    * ```
    */
-  send(body?: EmailSendParams, options?: Core.RequestOptions): Core.APIPromise<EmailSendResponse>;
-  send(options?: Core.RequestOptions): Core.APIPromise<EmailSendResponse>;
   send(
-    body: EmailSendParams | Core.RequestOptions = {},
-    options?: Core.RequestOptions,
-  ): Core.APIPromise<EmailSendResponse> {
-    if (isRequestOptions(body)) {
-      return this.send({}, body);
-    }
+    body: EmailSendParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<EmailSendResponse> {
     return this._client.post('/v1/email', { body, ...options });
   }
 }

package/src/resources/files.ts

@@ -1,7 +1,9 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../resource';
-import * as Core from '../core';
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
 
 /**
  * Access files, which are the items within Vals
@@ -10,8 +12,8 @@ export class Files extends APIResource {
   /**
    * Get file metadata by file ID
    */
-  retrieve(fileId: string, options?: Core.RequestOptions): Core.APIPromise<FileRetrieveResponse> {
-    return this._client.get(`/v2/files/${fileId}`, options);
+  retrieve(fileID: string, options?: RequestOptions): APIPromise<FileRetrieveResponse> {
+    return this._client.get(path`/v2/files/${fileID}`, options);
   }
 }
 

package/src/resources/index.ts

@@ -6,8 +6,7 @@ export { Blobs, type BlobListResponse, type BlobListParams, type BlobStoreParams
 export { Emails, type EmailSendResponse, type EmailSendParams } from './emails';
 export { Files, type FileRetrieveResponse } from './files';
 export { Me } from './me/me';
-export { OrgListResponsesPageCursorURL, Orgs, type OrgListResponse, type OrgListParams } from './orgs';
-export { Search } from './search/search';
+export { Orgs, type OrgListResponse, type OrgListParams, type OrgListResponsesPageCursorURL } from './orgs';
 export { Sqlite, type SqliteBatchResponse, type SqliteBatchParams, type SqliteExecuteParams } from './sqlite';
 export { Telemetry } from './telemetry/telemetry';
 export { Users } from './users';

package/src/resources/me/me.ts

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../resource';
+import { APIResource } from '../../core/resource';
 import * as ProfileAPI from './profile';
 import { Profile, ProfileRetrieveResponse } from './profile';
 import * as ValsAPI from './vals';

package/src/resources/me/profile.ts

@@ -1,13 +1,14 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../resource';
-import * as Core from '../../core';
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
 
 export class Profile extends APIResource {
   /**
    * Get profile information for the current user
    */
-  retrieve(options?: Core.RequestOptions): Core.APIPromise<ProfileRetrieveResponse> {
+  retrieve(options?: RequestOptions): APIPromise<ProfileRetrieveResponse> {
     return this._client.get('/v1/me', options);
   }
 }