diff --git a/codegen/layouts/endpoints.hbs b/codegen/layouts/endpoints.hbs index 319fe2a8..73a1819b 100644 --- a/codegen/layouts/endpoints.hbs +++ b/codegen/layouts/endpoints.hbs @@ -15,6 +15,10 @@ import { } from './{{fileName}}' {{/each}} +/** + * HTTP client for the Seam API{{#if withoutWorkspace}} not scoped to a workspace{{/if}} + * with endpoints keyed by their path, e.g., `seam.get['/devices/list']()`. + */ export class {{className}} { {{#if withoutWorkspace}} {{> route-class-methods-without-workspace }} diff --git a/codegen/layouts/partials/route-class-methods-without-workspace.hbs b/codegen/layouts/partials/route-class-methods-without-workspace.hbs index 9184cfde..74013209 100644 --- a/codegen/layouts/partials/route-class-methods-without-workspace.hbs +++ b/codegen/layouts/partials/route-class-methods-without-workspace.hbs @@ -7,6 +7,9 @@ constructor(options: SeamHttpWithoutWorkspaceOptions = {}) { this.defaults = limitToSeamHttpRequestOptions(opts) } +/** + * Creates a new {{className}} from an existing HTTP client. + */ static fromClient( client: SeamHttpWithoutWorkspaceOptionsWithClient['client'], options: Omit = {}, @@ -18,6 +21,10 @@ static fromClient( return new {{className}}(constructorOptions) } +/** + * Creates a new {{className}} authenticated with a console session token + * and not scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken['consoleSessionToken'], options: Omit< @@ -38,6 +45,10 @@ static fromConsoleSessionToken( return new {{className}}(constructorOptions) } +/** + * Creates a new {{className}} authenticated with a personal access token + * and not scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken['personalAccessToken'], options: Omit< diff --git a/codegen/layouts/partials/route-class-methods.hbs b/codegen/layouts/partials/route-class-methods.hbs index 135b92bc..4a5dce56 100644 --- a/codegen/layouts/partials/route-class-methods.hbs +++ b/codegen/layouts/partials/route-class-methods.hbs @@ -7,6 +7,9 @@ constructor(apiKeyOrOptions: string | SeamHttpOptions = {}) { this.defaults = limitToSeamHttpRequestOptions(options) } +/** + * Creates a new {{className}} from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -18,6 +21,9 @@ static fromClient( return new {{className}}(constructorOptions) } +/** + * Creates a new {{className}} authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -29,6 +35,9 @@ static fromApiKey( return new {{className}}(constructorOptions) } +/** + * Creates a new {{className}} authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -43,6 +52,11 @@ static fromClientSessionToken( return new {{className}}(constructorOptions) } +/** + * Creates a new {{className}} authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -63,6 +77,10 @@ static async fromPublishableKey( return {{className}}.fromClientSessionToken(token, options) } +/** + * Creates a new {{className}} authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -80,6 +98,10 @@ static fromConsoleSessionToken( return new {{className}}(constructorOptions) } +/** + * Creates a new {{className}} authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -97,12 +119,21 @@ static fromPersonalAccessToken( return new {{className}}(constructorOptions) } +/** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } +/** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/codegen/layouts/partials/route-class-subroute.hbs b/codegen/layouts/partials/route-class-subroute.hbs index 5220f635..ba42daf1 100644 --- a/codegen/layouts/partials/route-class-subroute.hbs +++ b/codegen/layouts/partials/route-class-subroute.hbs @@ -1,3 +1,6 @@ +/** + * Client for the Seam API {{routePath}} routes. + */ get {{ methodName }}(): {{ className }} { return {{ className }}.fromClient(this.client, this.defaults) } diff --git a/codegen/layouts/resource.hbs b/codegen/layouts/resource.hbs index afe4a92f..584d51aa 100644 --- a/codegen/layouts/resource.hbs +++ b/codegen/layouts/resource.hbs @@ -14,11 +14,23 @@ interface BatchResourceMap { {{/each}} } +{{#if (or (trim resources.[0].description) resources.[0].isDeprecated)}} {{> doc resources.[0]}} +{{else}} +/** + * Represents a {{typeName}} resource of the Seam API. + */ +{{/if}} export type {{typeName}} = { [K in TKey]?: Array | undefined } {{else}} +{{#if (or (trim resources.[0].description) resources.[0].isDeprecated)}} {{> doc resources.[0]}} +{{else}} +/** + * Represents a {{typeName}} resource of the Seam API. + */ +{{/if}} export type {{typeName}} = {{#each resources}}{{#unless @first}} | {{/unless}}{{> resource-object properties=properties}}{{/each}} {{/if}} diff --git a/codegen/layouts/route.hbs b/codegen/layouts/route.hbs index 388d04d1..45fd7fc5 100644 --- a/codegen/layouts/route.hbs +++ b/codegen/layouts/route.hbs @@ -12,6 +12,20 @@ import { assertValidRequestParameters } from 'lib/request-parameters.js' import type { RequireAtLeastOne } from 'lib/request-parameters.js' {{/if}} +{{#if routePath}} +/** + * Client for the Seam API {{routePath}} routes. + */ +{{else}} +/** + * HTTP client for the Seam API. + * + * Create a client with the constructor + * or one of the static factory methods, e.g., `fromApiKey`. + * Each Seam API route is available under its corresponding property, + * e.g., use `seam.devices.list()` to call the `/devices/list` endpoint. + */ +{{/if}} export class {{className}} { {{> route-class-methods }} diff --git a/codegen/layouts/without-workspace.hbs b/codegen/layouts/without-workspace.hbs index 927ffedf..3d7d54a4 100644 --- a/codegen/layouts/without-workspace.hbs +++ b/codegen/layouts/without-workspace.hbs @@ -7,9 +7,19 @@ import { SeamHttpWorkspaces } from 'lib/routes/workspaces/index.js' +/** + * HTTP client for the Seam API not scoped to a workspace. + * + * Use this client to list or create workspaces, + * e.g., when authenticated with a personal access token + * or console session token. + */ export class SeamHttpWithoutWorkspace { {{> route-class-methods-without-workspace }} + /** + * Client for the Seam API /workspaces routes available without a workspace. + */ get workspaces(): Pick { return SeamHttpWorkspaces.fromClient(this.client, this.defaults) } diff --git a/codegen/lib/layouts/route.ts b/codegen/lib/layouts/route.ts index 509617c1..49edfc1e 100644 --- a/codegen/lib/layouts/route.ts +++ b/codegen/lib/layouts/route.ts @@ -6,6 +6,7 @@ import { getResourceTypeName } from './resources.js' export interface RouteLayoutContext { className: string + routePath: string | null endpoints: EndpointLayoutContext[] subroutes: SubrouteLayoutContext[] skipClientSessionImport: boolean @@ -48,6 +49,7 @@ export interface SubrouteLayoutContext { methodName: string className: string fileName: string + routePath: string } interface ResourceTypeImport { @@ -61,6 +63,7 @@ export const setRouteLayoutContext = ( nodes: Array, ): void => { file.className = getClassName(node?.path ?? null) + file.routePath = node?.path ?? null file.skipClientSessionImport = node == null || node?.path === '/client_sessions' file.needsActionAttemptsImport = @@ -102,6 +105,7 @@ const getSubrouteLayoutContext = ( fileName: `${kebabCase(route.name)}/index.js`, methodName: camelCase(route.name), className: getClassName(route.path), + routePath: route.path, } } diff --git a/eslint.config.ts b/eslint.config.ts index 77975224..81b59c10 100644 --- a/eslint.config.ts +++ b/eslint.config.ts @@ -1,11 +1,37 @@ import { globalIgnores } from 'eslint/config' import importPlugin from 'eslint-plugin-import' +import jsdoc from 'eslint-plugin-jsdoc' import simpleImportSort from 'eslint-plugin-simple-import-sort' import unusedImports from 'eslint-plugin-unused-imports' import neostandard, { resolveIgnoresFromGitignore } from 'neostandard' const files = ['**/*.{ts,tsx}'] +// The public API is the export closure of src/index.ts. +// Only these files contain exports reachable from the package entrypoint, +// so only they must document their exports. +// Errors in src/lib/resources and src/lib/routes must be fixed +// in the codegen/layouts templates followed by npm run generate. +const publicApiFiles = [ + 'src/lib/auth.ts', + 'src/lib/error-interceptor.ts', + 'src/lib/openapi.ts', + 'src/lib/options.ts', + 'src/lib/request-options.ts', + 'src/lib/resolve-action-attempt.ts', + 'src/lib/resources/**/*.ts', + 'src/lib/routes/**/*.ts', + 'src/lib/seam-http-error.ts', + 'src/lib/seam-http-request.ts', + 'src/lib/seam-paginator.ts', + 'src/lib/token.ts', +] + +// The generated endpoint Parameters, Response, Request, and Options types +// are self-describing, so exported types in generated route files +// do not require documentation. +const generatedRouteFiles = ['src/lib/routes/**/*.ts'] + export default [ globalIgnores(resolveIgnoresFromGitignore()), ...neostandard({ ts: true, noStyle: true }), @@ -73,6 +99,74 @@ export default [ ], }, }, + { + ...jsdoc.configs['flat/recommended-typescript-error'], + files: publicApiFiles, + rules: { + ...jsdoc.configs['flat/recommended-typescript-error']?.rules, + 'jsdoc/require-jsdoc': [ + 'error', + { + publicOnly: true, + require: { + ArrowFunctionExpression: true, + ClassDeclaration: true, + ClassExpression: true, + FunctionDeclaration: true, + FunctionExpression: true, + MethodDefinition: false, + }, + contexts: [ + 'ExportNamedDeclaration > TSInterfaceDeclaration', + 'ExportNamedDeclaration > TSTypeAliasDeclaration', + 'ExportNamedDeclaration > TSEnumDeclaration', + ], + checkConstructors: false, + checkGetters: false, + checkSetters: false, + enableFixer: false, + }, + ], + 'jsdoc/require-description': [ + 'error', + { + contexts: ['any'], + exemptedBy: ['deprecated', 'inheritdoc', 'internal', 'see'], + }, + ], + 'jsdoc/require-param': 'off', + 'jsdoc/require-returns': 'off', + 'jsdoc/require-yields': 'off', + // Types belong in the TypeScript type annotations, not the JSDoc tags. + 'jsdoc/require-throws-type': 'off', + 'jsdoc/tag-lines': ['error', 'never', { startLines: 1 }], + // Conflicts with how Prettier formats JSDoc inside union types. + 'jsdoc/check-alignment': 'off', + }, + }, + { + files: generatedRouteFiles, + rules: { + 'jsdoc/require-jsdoc': [ + 'error', + { + publicOnly: true, + require: { + ArrowFunctionExpression: true, + ClassDeclaration: true, + ClassExpression: true, + FunctionDeclaration: true, + FunctionExpression: true, + MethodDefinition: false, + }, + checkConstructors: false, + checkGetters: false, + checkSetters: false, + enableFixer: false, + }, + ], + }, + }, { files, plugins: { diff --git a/package-lock.json b/package-lock.json index 1d5b951c..3c17bd70 100644 --- a/package-lock.json +++ b/package-lock.json @@ -27,6 +27,7 @@ "eslint": "^9.31.0", "eslint-import-resolver-typescript": "^4.4.5", "eslint-plugin-import": "^2.32.0", + "eslint-plugin-jsdoc": "^64.1.0", "eslint-plugin-simple-import-sort": "^12.1.1", "eslint-plugin-unused-imports": "^4.1.4", "execa": "^10.0.0", @@ -101,6 +102,47 @@ "tslib": "^2.4.0" } }, + "node_modules/@es-joy/jsdoccomment": { + "version": "0.95.0", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.95.0.tgz", + "integrity": "sha512-jbzwtRPuw1Nzld0lacvr1vwzPU/6zEHFGK5YOTstl2MQYMZBuKmSW3HMuEwsq1v4meK5Do4lizxyd/hi25rCZg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.9", + "@typescript-eslint/types": "^8.67.0", + "comment-parser": "1.4.8", + "esquery": "^1.7.0", + "jsdoc-type-pratt-parser": "~9.1.1" + }, + "engines": { + "node": "^22.22.2 || >=24.15.0" + } + }, + "node_modules/@es-joy/jsdoccomment/node_modules/@typescript-eslint/types": { + "version": "8.67.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.67.0.tgz", + "integrity": "sha512-sBtgslww8nsMYUjhdPBiSyUqSzT8uR6g93A2QXnQC8+cGdjz0CyaOdqHDRJb1AtORbZCNUJBBeFA/tNR2uQmww==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/@es-joy/resolve.exports": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@es-joy/resolve.exports/-/resolve.exports-1.2.0.tgz", + "integrity": "sha512-Q9hjxWI5xBM+qW2enxfe8wDKdFWMfd0Z29k5ZJnuBqD/CasY5Zryj09aCA6owbGATWz+39p5uIdaHXpopOcG8g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10" + } + }, "node_modules/@esbuild/aix-ppc64": { "version": "0.28.2", "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz", @@ -1188,6 +1230,19 @@ "dev": true, "license": "MIT" }, + "node_modules/@sindresorhus/base62": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/base62/-/base62-1.0.0.tgz", + "integrity": "sha512-TeheYy0ILzBEI/CO55CP6zJCSdSWeRtGnHy8U8dWSUH4I68iqTsy7HkMktR4xakThc9jotkPQUXT4ITdbV7cHA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/@sindresorhus/merge-streams": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-4.0.0.tgz", @@ -1710,9 +1765,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1727,9 +1779,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1744,9 +1793,6 @@ "loong64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1761,9 +1807,6 @@ "loong64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1778,9 +1821,6 @@ "ppc64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1795,9 +1835,6 @@ "riscv64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1812,9 +1849,6 @@ "riscv64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1829,9 +1863,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1846,9 +1877,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1863,9 +1891,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -2123,6 +2148,16 @@ "url": "https://github.com/sponsors/jonschlinkert" } }, + "node_modules/are-docs-informative": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/are-docs-informative/-/are-docs-informative-0.1.1.tgz", + "integrity": "sha512-sqRsNQBwbKLRX0jV5Cu5uzmtflf892n4Vukz7T659ebL4pz3mpOqCMU7lxMoBTFwnp10E3YB5ZcyHM41W5bcDA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, "node_modules/argparse": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", @@ -2923,6 +2958,16 @@ "node": ">=16" } }, + "node_modules/comment-parser": { + "version": "1.4.8", + "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.4.8.tgz", + "integrity": "sha512-rKZTGo4fzKYna8UcL0isTg5wkBNla7bxTypLwZQXjIdi++IdP1OJ41rI5Mti3/jltkPujbu4i9LIARYA+zpotQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 12.0.0" + } + }, "node_modules/common-path-prefix": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/common-path-prefix/-/common-path-prefix-3.0.0.tgz", @@ -3918,6 +3963,79 @@ "semver": "bin/semver.js" } }, + "node_modules/eslint-plugin-jsdoc": { + "version": "64.1.0", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-64.1.0.tgz", + "integrity": "sha512-UyAR/zVWn1jgIM/7eDMeLHuqLVtqKtamNVE0M7mdcZtFkWdYlNvDVDzyCCcURmLe66JpTZkMM3ZM3zjiVvIByA==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "@es-joy/jsdoccomment": "~0.95.0", + "@es-joy/resolve.exports": "1.2.0", + "are-docs-informative": "^0.1.1", + "comment-parser": "1.4.8", + "debug": "^4.4.3", + "escape-string-regexp": "^5.0.0", + "espree": "^11.2.0", + "esquery": "^1.7.0", + "html-entities": "^2.6.0", + "object-deep-merge": "^2.0.1", + "parse-imports-exports": "^0.2.4", + "semver": "^7.8.5", + "spdx-expression-parse": "^5.0.0", + "to-valid-identifier": "^1.0.0" + }, + "engines": { + "node": "^22.22.2 || >=24.15.0" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0" + } + }, + "node_modules/eslint-plugin-jsdoc/node_modules/escape-string-regexp": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz", + "integrity": "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/eslint-plugin-jsdoc/node_modules/eslint-visitor-keys": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-5.0.1.tgz", + "integrity": "sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, + "node_modules/eslint-plugin-jsdoc/node_modules/espree": { + "version": "11.2.0", + "resolved": "https://registry.npmjs.org/espree/-/espree-11.2.0.tgz", + "integrity": "sha512-7p3DrVEIopW1B1avAGLuCSh1jubc01H2JHc8B4qqGblmg5gI9yumBgACjWo4JlIc04ufug4xJ3SQI8HkS/Rgzw==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "acorn": "^8.16.0", + "acorn-jsx": "^5.3.2", + "eslint-visitor-keys": "^5.0.1" + }, + "engines": { + "node": "^20.19.0 || ^22.13.0 || >=24" + }, + "funding": { + "url": "https://opencollective.com/eslint" + } + }, "node_modules/eslint-plugin-n": { "version": "17.24.0", "resolved": "https://registry.npmjs.org/eslint-plugin-n/-/eslint-plugin-n-17.24.0.tgz", @@ -5138,6 +5256,23 @@ "node": ">= 6" } }, + "node_modules/html-entities": { + "version": "2.6.0", + "resolved": "https://registry.npmjs.org/html-entities/-/html-entities-2.6.0.tgz", + "integrity": "sha512-kig+rMn/QOVRvr7c86gQ8lWXq+Hkv6CbAH1hLu+RG338StTpE8Z0b44SDVaqVu7HGKf27frdmUYEs9hTUX/cLQ==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/mdevils" + }, + { + "type": "patreon", + "url": "https://patreon.com/mdevils" + } + ], + "license": "MIT" + }, "node_modules/html-escaper": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz", @@ -6019,6 +6154,19 @@ "js-yaml": "bin/js-yaml.js" } }, + "node_modules/jsdoc-type-pratt-parser": { + "version": "9.1.1", + "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-9.1.1.tgz", + "integrity": "sha512-kojSbQb9iQM2bk2PmHiKa3reG0U4v2gN9U8D8+eCQq+4KM5ZXBUyBVeF8KmR0RiwqyrW4+uVWYWTOLnpsavnkw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.9" + }, + "engines": { + "node": "^22.22.2 || >=24.15.0" + } + }, "node_modules/json-buffer": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz", @@ -7128,6 +7276,13 @@ "node": ">=0.10.0" } }, + "node_modules/object-deep-merge": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/object-deep-merge/-/object-deep-merge-2.0.1.tgz", + "integrity": "sha512-aKttDKcU3pyZqKcCkDhsMn70WmZFG2JGDQLP9EcLyTSIFQRCPWLAmBZRLJnrVUrhPG1jETEEbfdgbNtJf1LyMg==", + "dev": true, + "license": "MIT" + }, "node_modules/object-inspect": { "version": "1.13.4", "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz", @@ -7390,6 +7545,16 @@ "node": ">=6" } }, + "node_modules/parse-imports-exports": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/parse-imports-exports/-/parse-imports-exports-0.2.4.tgz", + "integrity": "sha512-4s6vd6dx1AotCx/RCI2m7t7GCh5bDRUtGNvRfHSP2wbBQdMi67pPe7mtzmgwcaQ8VKK/6IB7Glfyu3qdZJPybQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "parse-statements": "1.0.11" + } + }, "node_modules/parse-ms": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/parse-ms/-/parse-ms-4.0.0.tgz", @@ -7403,6 +7568,13 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/parse-statements": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/parse-statements/-/parse-statements-1.0.11.tgz", + "integrity": "sha512-HlsyYdMBnbPQ9Jr/VgJ1YF4scnldvJpJxCVx6KgqPL4dxppsWrJHCIIxQXMJrqGnsRkNPATbeMJ8Yxu7JMsYcA==", + "dev": true, + "license": "MIT" + }, "node_modules/path-exists": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", @@ -7896,6 +8068,19 @@ "license": "MIT", "peer": true }, + "node_modules/reserved-identifiers": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/reserved-identifiers/-/reserved-identifiers-1.2.0.tgz", + "integrity": "sha512-yE7KUfFvaBFzGPs5H3Ops1RevfUEsDc5Iz65rOwWg4lE8HJSYtle77uul3+573457oHvBKuHYDl/xqUkKpEEdw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/resolve": { "version": "2.0.0-next.7", "resolved": "https://registry.npmjs.org/resolve/-/resolve-2.0.0-next.7.tgz", @@ -8337,6 +8522,31 @@ "node": ">=0.10.0" } }, + "node_modules/spdx-exceptions": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/spdx-exceptions/-/spdx-exceptions-2.5.0.tgz", + "integrity": "sha512-PiU42r+xO4UbUS1buo3LPJkjlO7430Xn5SVAhdpzzsPHsjbYVflnnFdATgabnLude+Cqu25p6N+g2lw/PFsa4w==", + "dev": true, + "license": "CC-BY-3.0" + }, + "node_modules/spdx-expression-parse": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-5.0.0.tgz", + "integrity": "sha512-vngmw3Rgn+o2arXNbnZaj5UtOEBuWBfvaI+Wc8GFfykIhA5/vdK9/Sp/XkLv63dykz2rxKDvKEHupF5P0FORcQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "spdx-exceptions": "^2.1.0", + "spdx-license-ids": "^3.0.0" + } + }, + "node_modules/spdx-license-ids": { + "version": "3.0.23", + "resolved": "https://registry.npmjs.org/spdx-license-ids/-/spdx-license-ids-3.0.23.tgz", + "integrity": "sha512-CWLcCCH7VLu13TgOH+r8p1O/Znwhqv/dbb6lqWy67G+pT1kHmeD/+V36AVb/vq8QMIQwVShJ6Ssl5FPh0fuSdw==", + "dev": true, + "license": "CC0-1.0" + }, "node_modules/split2": { "version": "4.2.0", "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz", @@ -8819,6 +9029,23 @@ "node": ">=8.0" } }, + "node_modules/to-valid-identifier": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/to-valid-identifier/-/to-valid-identifier-1.0.0.tgz", + "integrity": "sha512-41wJyvKep3yT2tyPqX/4blcfybknGB4D+oETKLs7Q76UiPqRpUJK3hr1nxelyYO0PHKVzJwlu0aCeEAsGI6rpw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@sindresorhus/base62": "^1.0.0", + "reserved-identifiers": "^1.0.0" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/tr46": { "version": "0.0.3", "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", diff --git a/package.json b/package.json index 1feeaffc..c4abaa8e 100644 --- a/package.json +++ b/package.json @@ -97,6 +97,7 @@ "eslint": "^9.31.0", "eslint-import-resolver-typescript": "^4.4.5", "eslint-plugin-import": "^2.32.0", + "eslint-plugin-jsdoc": "^64.1.0", "eslint-plugin-simple-import-sort": "^12.1.1", "eslint-plugin-unused-imports": "^4.1.4", "execa": "^10.0.0", diff --git a/src/index.ts b/src/index.ts index 9ebc7c8e..93a8f447 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,2 +1,7 @@ +/** + * JavaScript HTTP client for the Seam API written in TypeScript. + * + * @packageDocumentation + */ export * from './lib/index.js' export * from '@seamapi/url-search-params-serializer' diff --git a/src/lib/auth.ts b/src/lib/auth.ts index 183aa458..1bef961b 100644 --- a/src/lib/auth.ts +++ b/src/lib/auth.ts @@ -33,6 +33,13 @@ type Options = | SeamHttpWithoutWorkspaceOptions | (SeamHttpOptions & { publishableKey?: string }) +/** + * Returns the HTTP headers used to authenticate with the Seam API + * for the given options. + * + * @throws {@link SeamHttpInvalidOptionsError} if no authentication option is set. + * @throws {@link SeamHttpInvalidTokenError} if a token has an unexpected format. + */ export const getAuthHeaders = (options: Options): Headers => { if ('publishableKey' in options && options.publishableKey != null) { return getAuthHeadersForPublishableKey(options.publishableKey) @@ -109,6 +116,12 @@ const getAuthHeadersForApiKey = ({ } } +/** + * Returns the HTTP headers used to authenticate with the Seam API + * using a client session token. + * + * @throws {@link SeamHttpInvalidTokenError} if the token has an unexpected format. + */ export const getAuthHeadersForClientSessionToken = ({ clientSessionToken, }: SeamHttpOptionsWithClientSessionToken): Headers => { @@ -248,6 +261,10 @@ const getAuthHeadersForPublishableKey = (publishableKey: string): Headers => { } } +/** + * Error thrown when SeamHttp receives a token with an unexpected format, + * e.g., a client session token passed as the apiKey option. + */ export class SeamHttpInvalidTokenError extends Error { constructor(message: string) { super(`SeamHttp received an invalid token: ${message}`) @@ -255,6 +272,11 @@ export class SeamHttpInvalidTokenError extends Error { } } +/** + * Logs a warning to the console when the user identifier key is an email address. + * An email is common knowledge or easily guessed, + * so it is an insecure user identifier key. + */ export const warnOnInsecureuserIdentifierKey = ( userIdentifierKey: string, ): void => { diff --git a/src/lib/error-interceptor.ts b/src/lib/error-interceptor.ts index ec297709..55ab80be 100644 --- a/src/lib/error-interceptor.ts +++ b/src/lib/error-interceptor.ts @@ -7,6 +7,12 @@ import { SeamHttpUnauthorizedError, } from './seam-http-error.js' +/** + * Axios response interceptor that converts errors from the Seam API + * into the corresponding {@link SeamHttpApiError}, + * e.g., {@link SeamHttpUnauthorizedError} or {@link SeamHttpInvalidInputError}. + * Rethrows non-Axios errors and errors without a Seam API error response unchanged. + */ export const errorInterceptor = async (err: unknown): Promise => { if (!isAxiosError(err)) throw err diff --git a/src/lib/index.ts b/src/lib/index.ts index 210bbaf1..bfae045a 100644 --- a/src/lib/index.ts +++ b/src/lib/index.ts @@ -3,12 +3,15 @@ export * from './error-interceptor.js' export * from './openapi.js' export * from './options.js' export { + type FailedActionAttempt, isSeamActionAttemptError, isSeamActionAttemptFailedError, isSeamActionAttemptTimeoutError, + type ResolveActionAttemptOptions, SeamActionAttemptError, SeamActionAttemptFailedError, SeamActionAttemptTimeoutError, + type SucceededActionAttempt, } from './resolve-action-attempt.js' export * from './resources/index.js' export * from './routes/index.js' diff --git a/src/lib/openapi.ts b/src/lib/openapi.ts index 527d59d9..d9ebd64a 100644 --- a/src/lib/openapi.ts +++ b/src/lib/openapi.ts @@ -1,6 +1,12 @@ import { createClient } from './client.js' import { defaultEndpoint, sdkHeaders } from './parse-options.js' +/** + * Fetches the OpenAPI schema describing the Seam API. + * + * @param endpoint - The Seam API endpoint to fetch the schema from. + * @returns The OpenAPI schema as parsed JSON. + */ export const getOpenapiSchema = async ( endpoint = defaultEndpoint, ): Promise => { diff --git a/src/lib/options.ts b/src/lib/options.ts index a91807f9..4b2984cd 100644 --- a/src/lib/options.ts +++ b/src/lib/options.ts @@ -6,12 +6,19 @@ import { export type { SeamHttpRequestOptions } from './request-options.js' +/** + * Options for creating a SeamHttpWithoutWorkspace client, + * which is not scoped to a single workspace. + */ export type SeamHttpWithoutWorkspaceOptions = | SeamHttpWithoutWorkspaceOptionsFromEnv | SeamHttpWithoutWorkspaceOptionsWithClient | SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken | SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken +/** + * Options for creating a SeamHttp client. + */ export type SeamHttpOptions = | SeamHttpOptionsFromEnv | SeamHttpOptionsWithClient @@ -21,28 +28,62 @@ export type SeamHttpOptions = | SeamHttpOptionsWithPersonalAccessToken interface SeamHttpCommonOptions extends ClientOptions, SeamHttpRequestOptions { + /** + * The Seam API endpoint, e.g., `https://connect.getseam.com`. + * Defaults to the SEAM_ENDPOINT or SEAM_API_URL environment variable, if set. + */ endpoint?: string } +/** + * Options for creating a SeamHttp client with `SeamHttp.fromPublishableKey`. + */ export interface SeamHttpFromPublishableKeyOptions extends SeamHttpCommonOptions {} +/** + * Options for creating a SeamHttp client that reads its configuration + * from the environment, e.g., the SEAM_API_KEY environment variable. + */ export interface SeamHttpOptionsFromEnv extends SeamHttpCommonOptions {} +/** + * Options for creating a SeamHttpWithoutWorkspace client that reads + * its configuration from the environment, + * e.g., the SEAM_PERSONAL_ACCESS_TOKEN environment variable. + */ export interface SeamHttpWithoutWorkspaceOptionsFromEnv extends SeamHttpCommonOptions {} +/** + * Options for creating a SeamHttpWithoutWorkspace client from an existing client. + */ export interface SeamHttpWithoutWorkspaceOptionsWithClient extends SeamHttpCommonOptions { client: Client } +/** + * Returns true if the options include a client. + * + * @throws {@link SeamHttpInvalidOptionsError} if the client option + * is used with any other option. + */ export const isSeamHttpWithoutWorkspaceOptionsWithClient = ( options: SeamHttpOptions, ): options is SeamHttpWithoutWorkspaceOptionsWithClient => isSeamHttpOptionsWithClient(options) +/** + * Options for creating a SeamHttp client from an existing client. + */ export interface SeamHttpOptionsWithClient extends SeamHttpRequestOptions { client: Client } +/** + * Returns true if the options include a client. + * + * @throws {@link SeamHttpInvalidOptionsError} if the client option + * is used with any other option. + */ export const isSeamHttpOptionsWithClient = ( options: SeamHttpOptions, ): options is SeamHttpOptionsWithClient => { @@ -61,10 +102,19 @@ export const isSeamHttpOptionsWithClient = ( return true } +/** + * Options for creating a SeamHttp client authenticated with an API key. + */ export interface SeamHttpOptionsWithApiKey extends SeamHttpCommonOptions { apiKey: string } +/** + * Returns true if the options include an apiKey. + * + * @throws {@link SeamHttpInvalidOptionsError} if the apiKey option + * is used with another authentication option. + */ export const isSeamHttpOptionsWithApiKey = ( options: SeamHttpOptions, ): options is SeamHttpOptionsWithApiKey => { @@ -92,10 +142,19 @@ export const isSeamHttpOptionsWithApiKey = ( return true } +/** + * Options for creating a SeamHttp client authenticated with a client session token. + */ export interface SeamHttpOptionsWithClientSessionToken extends SeamHttpCommonOptions { clientSessionToken: string } +/** + * Returns true if the options include a clientSessionToken. + * + * @throws {@link SeamHttpInvalidOptionsError} if the clientSessionToken option + * is used with another authentication option. + */ export const isSeamHttpOptionsWithClientSessionToken = ( options: SeamHttpOptions, ): options is SeamHttpOptionsWithClientSessionToken => { @@ -123,10 +182,20 @@ export const isSeamHttpOptionsWithClientSessionToken = ( return true } +/** + * Options for creating a SeamHttpWithoutWorkspace client + * authenticated with a console session token. + */ export interface SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken extends SeamHttpCommonOptions { consoleSessionToken: string } +/** + * Returns true if the options include a consoleSessionToken. + * + * @throws {@link SeamHttpInvalidOptionsError} if the consoleSessionToken option + * is used with another authentication option. + */ export const isSeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken = ( options: SeamHttpOptions, ): options is SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken => { @@ -154,11 +223,21 @@ export const isSeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken = ( return true } +/** + * Options for creating a SeamHttp client + * authenticated with a console session token and scoped to a workspace. + */ export interface SeamHttpOptionsWithConsoleSessionToken extends SeamHttpCommonOptions { consoleSessionToken: string workspaceId: string } +/** + * Returns true if the options include a consoleSessionToken and a workspaceId. + * + * @throws {@link SeamHttpInvalidOptionsError} if the consoleSessionToken option + * is used with another authentication option or without the workspaceId option. + */ export const isSeamHttpOptionsWithConsoleSessionToken = ( options: SeamHttpOptions, ): options is SeamHttpOptionsWithConsoleSessionToken => { @@ -175,10 +254,20 @@ export const isSeamHttpOptionsWithConsoleSessionToken = ( return true } +/** + * Options for creating a SeamHttpWithoutWorkspace client + * authenticated with a personal access token. + */ export interface SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken extends SeamHttpCommonOptions { personalAccessToken: string } +/** + * Returns true if the options include a personalAccessToken. + * + * @throws {@link SeamHttpInvalidOptionsError} if the personalAccessToken option + * is used with another authentication option. + */ export const isSeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken = ( options: SeamHttpOptions, ): options is SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken => { @@ -206,11 +295,21 @@ export const isSeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken = ( return true } +/** + * Options for creating a SeamHttp client + * authenticated with a personal access token and scoped to a workspace. + */ export interface SeamHttpOptionsWithPersonalAccessToken extends SeamHttpCommonOptions { personalAccessToken: string workspaceId: string } +/** + * Returns true if the options include a personalAccessToken and a workspaceId. + * + * @throws {@link SeamHttpInvalidOptionsError} if the personalAccessToken option + * is used with another authentication option or without the workspaceId option. + */ export const isSeamHttpOptionsWithPersonalAccessToken = ( options: SeamHttpOptions, ): options is SeamHttpOptionsWithPersonalAccessToken => { @@ -227,6 +326,9 @@ export const isSeamHttpOptionsWithPersonalAccessToken = ( return true } +/** + * Error thrown when a SeamHttp client is created with invalid options. + */ export class SeamHttpInvalidOptionsError extends Error { constructor(message: string) { super(`SeamHttp received invalid options: ${message}`) @@ -234,6 +336,9 @@ export class SeamHttpInvalidOptionsError extends Error { } } +/** + * Error thrown when a SeamHttpWithoutWorkspace client is created with invalid options. + */ export class SeamHttpWithoutWorkspaceInvalidOptionsError extends Error { constructor(message: string) { super(`SeamHttpWithoutWorkspace received invalid options: ${message}`) diff --git a/src/lib/request-options.ts b/src/lib/request-options.ts index e403a4f7..0fad41d8 100644 --- a/src/lib/request-options.ts +++ b/src/lib/request-options.ts @@ -1,9 +1,22 @@ import type { ResolveActionAttemptOptions } from './resolve-action-attempt.js' +/** + * Options for how a {@link SeamHttpRequest} is executed. + */ export interface SeamHttpRequestOptions { + /** + * Controls whether to wait for the action attempt to resolve + * when a request returns an action attempt. + * Pass a boolean to toggle waiting, + * or {@link ResolveActionAttemptOptions} to also configure + * the timeout and polling interval. + */ waitForActionAttempt?: boolean | ResolveActionAttemptOptions } +/** + * Returns true if the key is the name of a {@link SeamHttpRequestOptions} property. + */ export const isSeamHttpRequestOption = ( key: string, ): key is keyof SeamHttpRequestOptions => { diff --git a/src/lib/resolve-action-attempt.ts b/src/lib/resolve-action-attempt.ts index 3064d511..e01607be 100644 --- a/src/lib/resolve-action-attempt.ts +++ b/src/lib/resolve-action-attempt.ts @@ -1,14 +1,35 @@ import type { ActionAttempt } from './resources/action-attempt.js' +/** + * Client used to poll action attempts by id, e.g., `SeamHttpActionAttempts`. + */ export interface ActionAttemptsClient { get(parameters: { action_attempt_id: string }): PromiseLike } +/** + * Options for waiting until an action attempt resolves. + */ export interface ResolveActionAttemptOptions { + /** + * Maximum time in milliseconds to wait for the action attempt to resolve. + */ timeout?: number + + /** + * Time in milliseconds to wait between polls of the action attempt. + */ pollingInterval?: number } +/** + * Polls a pending action attempt until it succeeds, fails, or times out. + * + * @returns The succeeded action attempt. + * @throws {@link SeamActionAttemptFailedError} if the action attempt fails. + * @throws {@link SeamActionAttemptTimeoutError} if the action attempt + * does not resolve within the timeout. + */ export const resolveActionAttempt = async ( actionAttempt: T, actionAttempts: ActionAttemptsClient, @@ -59,12 +80,18 @@ const pollActionAttempt = async ( ) } +/** + * Returns true if the error is a {@link SeamActionAttemptError}. + */ export const isSeamActionAttemptError = ( error: unknown, ): error is SeamActionAttemptError => { return error instanceof SeamActionAttemptError } +/** + * Error relating to an action attempt. + */ export class SeamActionAttemptError extends Error { actionAttempt: T @@ -75,15 +102,24 @@ export class SeamActionAttemptError extends Error { } } +/** + * Returns true if the error is a {@link SeamActionAttemptFailedError}. + */ export const isSeamActionAttemptFailedError = ( error: unknown, ): error is SeamActionAttemptFailedError => { return error instanceof SeamActionAttemptFailedError } +/** + * Error thrown when an action attempt fails. + */ export class SeamActionAttemptFailedError< T extends ActionAttempt, > extends SeamActionAttemptError { + /** + * Error type returned by the Seam API for the failed action attempt. + */ code: string constructor(actionAttempt: FailedActionAttempt) { @@ -93,12 +129,18 @@ export class SeamActionAttemptFailedError< } } +/** + * Returns true if the error is a {@link SeamActionAttemptTimeoutError}. + */ export const isSeamActionAttemptTimeoutError = ( error: unknown, ): error is SeamActionAttemptTimeoutError => { return error instanceof SeamActionAttemptTimeoutError } +/** + * Error thrown when an action attempt does not resolve within the timeout. + */ export class SeamActionAttemptTimeoutError< T extends ActionAttempt, > extends SeamActionAttemptError { @@ -120,10 +162,16 @@ const isFailedActionAttempt = ( actionAttempt: T, ): actionAttempt is FailedActionAttempt => actionAttempt.status === 'error' +/** + * An action attempt that has succeeded. + */ export type SucceededActionAttempt = T & { status: 'success' } +/** + * An action attempt that has failed. + */ export type FailedActionAttempt = T & { status: 'error' } diff --git a/src/lib/resources/acs-system.ts b/src/lib/resources/acs-system.ts index 9237ece2..771dcc95 100644 --- a/src/lib/resources/acs-system.ts +++ b/src/lib/resources/acs-system.ts @@ -31,6 +31,7 @@ export type AcsSystem = { /** * IDs of the [connected accounts](https://docs.seam.co/core-concepts/connected-accounts) associated with the [access control system](https://docs.seam.co/low-level-apis/access-systems). + * * @deprecated Use `connected_account_id`. */ connected_account_ids: Array diff --git a/src/lib/resources/client-session.ts b/src/lib/resources/client-session.ts index d52099a3..5efe1147 100644 --- a/src/lib/resources/client-session.ts +++ b/src/lib/resources/client-session.ts @@ -64,6 +64,7 @@ export type ClientSession = { user_identity_id?: string | undefined /** * IDs of the [user identities](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) associated with the client session. + * * @deprecated Use `user_identity_id` instead. */ user_identity_ids: Array diff --git a/src/lib/resources/connected-account.ts b/src/lib/resources/connected-account.ts index 789f7d45..a99c3a35 100644 --- a/src/lib/resources/connected-account.ts +++ b/src/lib/resources/connected-account.ts @@ -217,6 +217,7 @@ export type ConnectedAccount = { time_zone?: string | undefined /** * User identifier associated with the connected account. + * * @deprecated Use `display_name` instead. */ user_identifier?: diff --git a/src/lib/resources/device-provider.ts b/src/lib/resources/device-provider.ts index 242e24a3..e7f97626 100644 --- a/src/lib/resources/device-provider.ts +++ b/src/lib/resources/device-provider.ts @@ -3,6 +3,9 @@ * Do not edit this file. */ +/** + * Represents a DeviceProvider resource of the Seam API. + */ export type DeviceProvider = { /** * Indicates whether the lock supports configuring automatic locking. diff --git a/src/lib/resources/device.ts b/src/lib/resources/device.ts index 37a0bccf..3f8432fd 100644 --- a/src/lib/resources/device.ts +++ b/src/lib/resources/device.ts @@ -593,6 +593,7 @@ export type Device = { time_zone?: string | undefined /** * Time zone of the device location. + * * @deprecated Use `time_zone` instead. */ timezone?: string | undefined @@ -713,6 +714,7 @@ export type Device = { /** * Name of the device. + * * @deprecated use device.display_name instead */ name: string @@ -723,6 +725,7 @@ export type Device = { noise_level_decibels?: number | undefined /** * Indicates whether it is currently possible to use offline access codes for the device. + * * @deprecated use device.can_program_offline_access_codes */ offline_access_codes_enabled?: boolean | undefined @@ -733,6 +736,7 @@ export type Device = { /** * Indicates whether it is currently possible to use online access codes for the device. + * * @deprecated use device.can_program_online_access_codes */ online_access_codes_enabled?: boolean | undefined @@ -1036,6 +1040,7 @@ export type Device = { | undefined /** * Site ID for a dormakaba Oracode device. + * * @deprecated Previously marked as "@DEPRECATED." */ site_id?: number | null | undefined @@ -1623,6 +1628,7 @@ export type Device = { | undefined /** * Metada for a Salto device. + * * @deprecated Use `salto_ks_metadata` instead. */ salto_metadata?: @@ -2181,6 +2187,7 @@ export type Device = { supports_backup_access_code_pool?: boolean | undefined /** * Active [thermostat schedule](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules). + * * @deprecated Use `active_thermostat_schedule_id` with `/thermostats/schedules/get` instead. */ active_thermostat_schedule?: @@ -2351,6 +2358,7 @@ export type Device = { 'off' | 'heat' | 'cool' | 'heat_cool' | 'eco' | undefined /** * Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions). + * * @deprecated Use 'thermostat_schedule.is_override_allowed' */ manual_override_allowed: boolean @@ -2452,6 +2460,7 @@ export type Device = { 'off' | 'heat' | 'cool' | 'heat_cool' | 'eco' | undefined /** * Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions). + * * @deprecated Use 'thermostat_schedule.is_override_allowed' */ manual_override_allowed?: boolean | undefined @@ -2543,6 +2552,7 @@ export type Device = { 'off' | 'heat' | 'cool' | 'heat_cool' | 'eco' | undefined /** * Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions). + * * @deprecated Use 'thermostat_schedule.is_override_allowed' */ manual_override_allowed?: boolean | undefined diff --git a/src/lib/resources/event.ts b/src/lib/resources/event.ts index c554cd97..2b4f3c84 100644 --- a/src/lib/resources/event.ts +++ b/src/lib/resources/event.ts @@ -3,6 +3,9 @@ * Do not edit this file. */ +/** + * Represents a SeamEvent resource of the Seam API. + */ export type SeamEvent = | { /** diff --git a/src/lib/resources/unmanaged-device.ts b/src/lib/resources/unmanaged-device.ts index 101d2384..feb12679 100644 --- a/src/lib/resources/unmanaged-device.ts +++ b/src/lib/resources/unmanaged-device.ts @@ -543,6 +543,7 @@ export type UnmanagedDevice = { time_zone?: string | undefined /** * Time zone of the device location. + * * @deprecated Use `time_zone` instead. */ timezone?: string | undefined @@ -641,12 +642,14 @@ export type UnmanagedDevice = { /** * Name of the device. + * * @deprecated use device.display_name instead */ name: string /** * Indicates whether it is currently possible to use offline access codes for the device. + * * @deprecated use device.can_program_offline_access_codes */ offline_access_codes_enabled?: boolean | undefined @@ -657,6 +660,7 @@ export type UnmanagedDevice = { /** * Indicates whether it is currently possible to use online access codes for the device. + * * @deprecated use device.can_program_online_access_codes */ online_access_codes_enabled?: boolean | undefined diff --git a/src/lib/routes/access-codes/access-codes.ts b/src/lib/routes/access-codes/access-codes.ts index 744eac8c..2fc0c16c 100644 --- a/src/lib/routes/access-codes/access-codes.ts +++ b/src/lib/routes/access-codes/access-codes.ts @@ -40,6 +40,9 @@ import { SeamPaginator } from 'lib/seam-paginator.js' import { SeamHttpAccessCodesSimulate } from './simulate/index.js' import { SeamHttpAccessCodesUnmanaged } from './unmanaged/index.js' +/** + * Client for the Seam API /access_codes routes. + */ export class SeamHttpAccessCodes { client: Client readonly defaults: Required @@ -50,6 +53,9 @@ export class SeamHttpAccessCodes { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAccessCodes from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -61,6 +67,9 @@ export class SeamHttpAccessCodes { return new SeamHttpAccessCodes(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodes authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -72,6 +81,9 @@ export class SeamHttpAccessCodes { return new SeamHttpAccessCodes(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodes authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -86,6 +98,11 @@ export class SeamHttpAccessCodes { return new SeamHttpAccessCodes(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodes authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -106,6 +123,10 @@ export class SeamHttpAccessCodes { return SeamHttpAccessCodes.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAccessCodes authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -123,6 +144,10 @@ export class SeamHttpAccessCodes { return new SeamHttpAccessCodes(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodes authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -140,12 +165,21 @@ export class SeamHttpAccessCodes { return new SeamHttpAccessCodes(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -165,10 +199,16 @@ export class SeamHttpAccessCodes { await clientSessions.get() } + /** + * Client for the Seam API /access_codes/simulate routes. + */ get simulate(): SeamHttpAccessCodesSimulate { return SeamHttpAccessCodesSimulate.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /access_codes/unmanaged routes. + */ get unmanaged(): SeamHttpAccessCodesUnmanaged { return SeamHttpAccessCodesUnmanaged.fromClient(this.client, this.defaults) } diff --git a/src/lib/routes/access-codes/simulate/simulate.ts b/src/lib/routes/access-codes/simulate/simulate.ts index a2958d79..5afafcaf 100644 --- a/src/lib/routes/access-codes/simulate/simulate.ts +++ b/src/lib/routes/access-codes/simulate/simulate.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /access_codes/simulate routes. + */ export class SeamHttpAccessCodesSimulate { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpAccessCodesSimulate { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAccessCodesSimulate from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpAccessCodesSimulate { return new SeamHttpAccessCodesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodesSimulate authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpAccessCodesSimulate { return new SeamHttpAccessCodesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodesSimulate authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpAccessCodesSimulate { return new SeamHttpAccessCodesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodesSimulate authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -100,6 +117,10 @@ export class SeamHttpAccessCodesSimulate { return SeamHttpAccessCodesSimulate.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAccessCodesSimulate authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -117,6 +138,10 @@ export class SeamHttpAccessCodesSimulate { return new SeamHttpAccessCodesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodesSimulate authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -134,12 +159,21 @@ export class SeamHttpAccessCodesSimulate { return new SeamHttpAccessCodesSimulate(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/access-codes/unmanaged/unmanaged.ts b/src/lib/routes/access-codes/unmanaged/unmanaged.ts index f76b8845..e90436d0 100644 --- a/src/lib/routes/access-codes/unmanaged/unmanaged.ts +++ b/src/lib/routes/access-codes/unmanaged/unmanaged.ts @@ -37,6 +37,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /access_codes/unmanaged routes. + */ export class SeamHttpAccessCodesUnmanaged { client: Client readonly defaults: Required @@ -47,6 +50,9 @@ export class SeamHttpAccessCodesUnmanaged { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAccessCodesUnmanaged from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -58,6 +64,9 @@ export class SeamHttpAccessCodesUnmanaged { return new SeamHttpAccessCodesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodesUnmanaged authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -69,6 +78,9 @@ export class SeamHttpAccessCodesUnmanaged { return new SeamHttpAccessCodesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodesUnmanaged authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -83,6 +95,11 @@ export class SeamHttpAccessCodesUnmanaged { return new SeamHttpAccessCodesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodesUnmanaged authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -103,6 +120,10 @@ export class SeamHttpAccessCodesUnmanaged { return SeamHttpAccessCodesUnmanaged.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAccessCodesUnmanaged authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -120,6 +141,10 @@ export class SeamHttpAccessCodesUnmanaged { return new SeamHttpAccessCodesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessCodesUnmanaged authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -137,12 +162,21 @@ export class SeamHttpAccessCodesUnmanaged { return new SeamHttpAccessCodesUnmanaged(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/access-grants/access-grants.ts b/src/lib/routes/access-grants/access-grants.ts index c5cf7ed3..9704189a 100644 --- a/src/lib/routes/access-grants/access-grants.ts +++ b/src/lib/routes/access-grants/access-grants.ts @@ -40,6 +40,9 @@ import { SeamPaginator } from 'lib/seam-paginator.js' import { SeamHttpAccessGrantsUnmanaged } from './unmanaged/index.js' +/** + * Client for the Seam API /access_grants routes. + */ export class SeamHttpAccessGrants { client: Client readonly defaults: Required @@ -50,6 +53,9 @@ export class SeamHttpAccessGrants { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAccessGrants from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -61,6 +67,9 @@ export class SeamHttpAccessGrants { return new SeamHttpAccessGrants(constructorOptions) } + /** + * Creates a new SeamHttpAccessGrants authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -72,6 +81,9 @@ export class SeamHttpAccessGrants { return new SeamHttpAccessGrants(constructorOptions) } + /** + * Creates a new SeamHttpAccessGrants authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -86,6 +98,11 @@ export class SeamHttpAccessGrants { return new SeamHttpAccessGrants(constructorOptions) } + /** + * Creates a new SeamHttpAccessGrants authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -106,6 +123,10 @@ export class SeamHttpAccessGrants { return SeamHttpAccessGrants.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAccessGrants authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -123,6 +144,10 @@ export class SeamHttpAccessGrants { return new SeamHttpAccessGrants(constructorOptions) } + /** + * Creates a new SeamHttpAccessGrants authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -140,12 +165,21 @@ export class SeamHttpAccessGrants { return new SeamHttpAccessGrants(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -165,6 +199,9 @@ export class SeamHttpAccessGrants { await clientSessions.get() } + /** + * Client for the Seam API /access_grants/unmanaged routes. + */ get unmanaged(): SeamHttpAccessGrantsUnmanaged { return SeamHttpAccessGrantsUnmanaged.fromClient(this.client, this.defaults) } diff --git a/src/lib/routes/access-grants/unmanaged/unmanaged.ts b/src/lib/routes/access-grants/unmanaged/unmanaged.ts index e693998a..daf503f6 100644 --- a/src/lib/routes/access-grants/unmanaged/unmanaged.ts +++ b/src/lib/routes/access-grants/unmanaged/unmanaged.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /access_grants/unmanaged routes. + */ export class SeamHttpAccessGrantsUnmanaged { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpAccessGrantsUnmanaged { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAccessGrantsUnmanaged from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpAccessGrantsUnmanaged { return new SeamHttpAccessGrantsUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessGrantsUnmanaged authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpAccessGrantsUnmanaged { return new SeamHttpAccessGrantsUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessGrantsUnmanaged authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpAccessGrantsUnmanaged { return new SeamHttpAccessGrantsUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessGrantsUnmanaged authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -100,6 +117,10 @@ export class SeamHttpAccessGrantsUnmanaged { return SeamHttpAccessGrantsUnmanaged.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAccessGrantsUnmanaged authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -117,6 +138,10 @@ export class SeamHttpAccessGrantsUnmanaged { return new SeamHttpAccessGrantsUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessGrantsUnmanaged authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -134,12 +159,21 @@ export class SeamHttpAccessGrantsUnmanaged { return new SeamHttpAccessGrantsUnmanaged(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/access-methods/access-methods.ts b/src/lib/routes/access-methods/access-methods.ts index 6094b550..b1d8f940 100644 --- a/src/lib/routes/access-methods/access-methods.ts +++ b/src/lib/routes/access-methods/access-methods.ts @@ -42,6 +42,9 @@ import { SeamPaginator } from 'lib/seam-paginator.js' import { SeamHttpAccessMethodsUnmanaged } from './unmanaged/index.js' +/** + * Client for the Seam API /access_methods routes. + */ export class SeamHttpAccessMethods { client: Client readonly defaults: Required @@ -52,6 +55,9 @@ export class SeamHttpAccessMethods { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAccessMethods from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -63,6 +69,9 @@ export class SeamHttpAccessMethods { return new SeamHttpAccessMethods(constructorOptions) } + /** + * Creates a new SeamHttpAccessMethods authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -74,6 +83,9 @@ export class SeamHttpAccessMethods { return new SeamHttpAccessMethods(constructorOptions) } + /** + * Creates a new SeamHttpAccessMethods authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -88,6 +100,11 @@ export class SeamHttpAccessMethods { return new SeamHttpAccessMethods(constructorOptions) } + /** + * Creates a new SeamHttpAccessMethods authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -108,6 +125,10 @@ export class SeamHttpAccessMethods { return SeamHttpAccessMethods.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAccessMethods authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -125,6 +146,10 @@ export class SeamHttpAccessMethods { return new SeamHttpAccessMethods(constructorOptions) } + /** + * Creates a new SeamHttpAccessMethods authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -142,12 +167,21 @@ export class SeamHttpAccessMethods { return new SeamHttpAccessMethods(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -167,6 +201,9 @@ export class SeamHttpAccessMethods { await clientSessions.get() } + /** + * Client for the Seam API /access_methods/unmanaged routes. + */ get unmanaged(): SeamHttpAccessMethodsUnmanaged { return SeamHttpAccessMethodsUnmanaged.fromClient(this.client, this.defaults) } diff --git a/src/lib/routes/access-methods/unmanaged/unmanaged.ts b/src/lib/routes/access-methods/unmanaged/unmanaged.ts index e6a0d615..85e75055 100644 --- a/src/lib/routes/access-methods/unmanaged/unmanaged.ts +++ b/src/lib/routes/access-methods/unmanaged/unmanaged.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /access_methods/unmanaged routes. + */ export class SeamHttpAccessMethodsUnmanaged { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpAccessMethodsUnmanaged { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAccessMethodsUnmanaged from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpAccessMethodsUnmanaged { return new SeamHttpAccessMethodsUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessMethodsUnmanaged authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpAccessMethodsUnmanaged { return new SeamHttpAccessMethodsUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessMethodsUnmanaged authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpAccessMethodsUnmanaged { return new SeamHttpAccessMethodsUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessMethodsUnmanaged authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -100,6 +117,10 @@ export class SeamHttpAccessMethodsUnmanaged { return SeamHttpAccessMethodsUnmanaged.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAccessMethodsUnmanaged authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -117,6 +138,10 @@ export class SeamHttpAccessMethodsUnmanaged { return new SeamHttpAccessMethodsUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpAccessMethodsUnmanaged authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -134,12 +159,21 @@ export class SeamHttpAccessMethodsUnmanaged { return new SeamHttpAccessMethodsUnmanaged(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/acs/access-groups/access-groups.ts b/src/lib/routes/acs/access-groups/access-groups.ts index 715ca00d..430da89c 100644 --- a/src/lib/routes/acs/access-groups/access-groups.ts +++ b/src/lib/routes/acs/access-groups/access-groups.ts @@ -36,6 +36,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /acs/access_groups routes. + */ export class SeamHttpAcsAccessGroups { client: Client readonly defaults: Required @@ -46,6 +49,9 @@ export class SeamHttpAcsAccessGroups { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAcsAccessGroups from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -57,6 +63,9 @@ export class SeamHttpAcsAccessGroups { return new SeamHttpAcsAccessGroups(constructorOptions) } + /** + * Creates a new SeamHttpAcsAccessGroups authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -68,6 +77,9 @@ export class SeamHttpAcsAccessGroups { return new SeamHttpAcsAccessGroups(constructorOptions) } + /** + * Creates a new SeamHttpAcsAccessGroups authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -82,6 +94,11 @@ export class SeamHttpAcsAccessGroups { return new SeamHttpAcsAccessGroups(constructorOptions) } + /** + * Creates a new SeamHttpAcsAccessGroups authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -102,6 +119,10 @@ export class SeamHttpAcsAccessGroups { return SeamHttpAcsAccessGroups.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAcsAccessGroups authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -119,6 +140,10 @@ export class SeamHttpAcsAccessGroups { return new SeamHttpAcsAccessGroups(constructorOptions) } + /** + * Creates a new SeamHttpAcsAccessGroups authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -136,12 +161,21 @@ export class SeamHttpAcsAccessGroups { return new SeamHttpAcsAccessGroups(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/acs/acs.ts b/src/lib/routes/acs/acs.ts index b431297f..ccab94d8 100644 --- a/src/lib/routes/acs/acs.ts +++ b/src/lib/routes/acs/acs.ts @@ -39,6 +39,9 @@ import { SeamHttpAcsEntrances } from './entrances/index.js' import { SeamHttpAcsSystems } from './systems/index.js' import { SeamHttpAcsUsers } from './users/index.js' +/** + * Client for the Seam API /acs routes. + */ export class SeamHttpAcs { client: Client readonly defaults: Required @@ -49,6 +52,9 @@ export class SeamHttpAcs { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAcs from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -60,6 +66,9 @@ export class SeamHttpAcs { return new SeamHttpAcs(constructorOptions) } + /** + * Creates a new SeamHttpAcs authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -71,6 +80,9 @@ export class SeamHttpAcs { return new SeamHttpAcs(constructorOptions) } + /** + * Creates a new SeamHttpAcs authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -85,6 +97,11 @@ export class SeamHttpAcs { return new SeamHttpAcs(constructorOptions) } + /** + * Creates a new SeamHttpAcs authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -105,6 +122,10 @@ export class SeamHttpAcs { return SeamHttpAcs.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAcs authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -122,6 +143,10 @@ export class SeamHttpAcs { return new SeamHttpAcs(constructorOptions) } + /** + * Creates a new SeamHttpAcs authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -139,12 +164,21 @@ export class SeamHttpAcs { return new SeamHttpAcs(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -164,26 +198,44 @@ export class SeamHttpAcs { await clientSessions.get() } + /** + * Client for the Seam API /acs/access_groups routes. + */ get accessGroups(): SeamHttpAcsAccessGroups { return SeamHttpAcsAccessGroups.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /acs/credentials routes. + */ get credentials(): SeamHttpAcsCredentials { return SeamHttpAcsCredentials.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /acs/encoders routes. + */ get encoders(): SeamHttpAcsEncoders { return SeamHttpAcsEncoders.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /acs/entrances routes. + */ get entrances(): SeamHttpAcsEntrances { return SeamHttpAcsEntrances.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /acs/systems routes. + */ get systems(): SeamHttpAcsSystems { return SeamHttpAcsSystems.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /acs/users routes. + */ get users(): SeamHttpAcsUsers { return SeamHttpAcsUsers.fromClient(this.client, this.defaults) } diff --git a/src/lib/routes/acs/credentials/credentials.ts b/src/lib/routes/acs/credentials/credentials.ts index e2281373..5be0828f 100644 --- a/src/lib/routes/acs/credentials/credentials.ts +++ b/src/lib/routes/acs/credentials/credentials.ts @@ -35,6 +35,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /acs/credentials routes. + */ export class SeamHttpAcsCredentials { client: Client readonly defaults: Required @@ -45,6 +48,9 @@ export class SeamHttpAcsCredentials { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAcsCredentials from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -56,6 +62,9 @@ export class SeamHttpAcsCredentials { return new SeamHttpAcsCredentials(constructorOptions) } + /** + * Creates a new SeamHttpAcsCredentials authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -67,6 +76,9 @@ export class SeamHttpAcsCredentials { return new SeamHttpAcsCredentials(constructorOptions) } + /** + * Creates a new SeamHttpAcsCredentials authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -81,6 +93,11 @@ export class SeamHttpAcsCredentials { return new SeamHttpAcsCredentials(constructorOptions) } + /** + * Creates a new SeamHttpAcsCredentials authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -101,6 +118,10 @@ export class SeamHttpAcsCredentials { return SeamHttpAcsCredentials.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAcsCredentials authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -118,6 +139,10 @@ export class SeamHttpAcsCredentials { return new SeamHttpAcsCredentials(constructorOptions) } + /** + * Creates a new SeamHttpAcsCredentials authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -135,12 +160,21 @@ export class SeamHttpAcsCredentials { return new SeamHttpAcsCredentials(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/acs/encoders/encoders.ts b/src/lib/routes/acs/encoders/encoders.ts index bcb15ade..d2f77649 100644 --- a/src/lib/routes/acs/encoders/encoders.ts +++ b/src/lib/routes/acs/encoders/encoders.ts @@ -38,6 +38,9 @@ import { SeamPaginator } from 'lib/seam-paginator.js' import { SeamHttpAcsEncodersSimulate } from './simulate/index.js' +/** + * Client for the Seam API /acs/encoders routes. + */ export class SeamHttpAcsEncoders { client: Client readonly defaults: Required @@ -48,6 +51,9 @@ export class SeamHttpAcsEncoders { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAcsEncoders from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -59,6 +65,9 @@ export class SeamHttpAcsEncoders { return new SeamHttpAcsEncoders(constructorOptions) } + /** + * Creates a new SeamHttpAcsEncoders authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -70,6 +79,9 @@ export class SeamHttpAcsEncoders { return new SeamHttpAcsEncoders(constructorOptions) } + /** + * Creates a new SeamHttpAcsEncoders authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -84,6 +96,11 @@ export class SeamHttpAcsEncoders { return new SeamHttpAcsEncoders(constructorOptions) } + /** + * Creates a new SeamHttpAcsEncoders authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -104,6 +121,10 @@ export class SeamHttpAcsEncoders { return SeamHttpAcsEncoders.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAcsEncoders authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -121,6 +142,10 @@ export class SeamHttpAcsEncoders { return new SeamHttpAcsEncoders(constructorOptions) } + /** + * Creates a new SeamHttpAcsEncoders authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -138,12 +163,21 @@ export class SeamHttpAcsEncoders { return new SeamHttpAcsEncoders(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -163,6 +197,9 @@ export class SeamHttpAcsEncoders { await clientSessions.get() } + /** + * Client for the Seam API /acs/encoders/simulate routes. + */ get simulate(): SeamHttpAcsEncodersSimulate { return SeamHttpAcsEncodersSimulate.fromClient(this.client, this.defaults) } diff --git a/src/lib/routes/acs/encoders/simulate/simulate.ts b/src/lib/routes/acs/encoders/simulate/simulate.ts index 01d3d2a7..eb8e9822 100644 --- a/src/lib/routes/acs/encoders/simulate/simulate.ts +++ b/src/lib/routes/acs/encoders/simulate/simulate.ts @@ -33,6 +33,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /acs/encoders/simulate routes. + */ export class SeamHttpAcsEncodersSimulate { client: Client readonly defaults: Required @@ -43,6 +46,9 @@ export class SeamHttpAcsEncodersSimulate { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAcsEncodersSimulate from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -54,6 +60,9 @@ export class SeamHttpAcsEncodersSimulate { return new SeamHttpAcsEncodersSimulate(constructorOptions) } + /** + * Creates a new SeamHttpAcsEncodersSimulate authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -65,6 +74,9 @@ export class SeamHttpAcsEncodersSimulate { return new SeamHttpAcsEncodersSimulate(constructorOptions) } + /** + * Creates a new SeamHttpAcsEncodersSimulate authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -79,6 +91,11 @@ export class SeamHttpAcsEncodersSimulate { return new SeamHttpAcsEncodersSimulate(constructorOptions) } + /** + * Creates a new SeamHttpAcsEncodersSimulate authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -99,6 +116,10 @@ export class SeamHttpAcsEncodersSimulate { return SeamHttpAcsEncodersSimulate.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAcsEncodersSimulate authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -116,6 +137,10 @@ export class SeamHttpAcsEncodersSimulate { return new SeamHttpAcsEncodersSimulate(constructorOptions) } + /** + * Creates a new SeamHttpAcsEncodersSimulate authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -133,12 +158,21 @@ export class SeamHttpAcsEncodersSimulate { return new SeamHttpAcsEncodersSimulate(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/acs/entrances/entrances.ts b/src/lib/routes/acs/entrances/entrances.ts index 1c5d93ef..22f18b56 100644 --- a/src/lib/routes/acs/entrances/entrances.ts +++ b/src/lib/routes/acs/entrances/entrances.ts @@ -37,6 +37,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /acs/entrances routes. + */ export class SeamHttpAcsEntrances { client: Client readonly defaults: Required @@ -47,6 +50,9 @@ export class SeamHttpAcsEntrances { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAcsEntrances from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -58,6 +64,9 @@ export class SeamHttpAcsEntrances { return new SeamHttpAcsEntrances(constructorOptions) } + /** + * Creates a new SeamHttpAcsEntrances authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -69,6 +78,9 @@ export class SeamHttpAcsEntrances { return new SeamHttpAcsEntrances(constructorOptions) } + /** + * Creates a new SeamHttpAcsEntrances authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -83,6 +95,11 @@ export class SeamHttpAcsEntrances { return new SeamHttpAcsEntrances(constructorOptions) } + /** + * Creates a new SeamHttpAcsEntrances authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -103,6 +120,10 @@ export class SeamHttpAcsEntrances { return SeamHttpAcsEntrances.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAcsEntrances authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -120,6 +141,10 @@ export class SeamHttpAcsEntrances { return new SeamHttpAcsEntrances(constructorOptions) } + /** + * Creates a new SeamHttpAcsEntrances authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -137,12 +162,21 @@ export class SeamHttpAcsEntrances { return new SeamHttpAcsEntrances(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/acs/systems/systems.ts b/src/lib/routes/acs/systems/systems.ts index d6571f37..a0f3136b 100644 --- a/src/lib/routes/acs/systems/systems.ts +++ b/src/lib/routes/acs/systems/systems.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /acs/systems routes. + */ export class SeamHttpAcsSystems { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpAcsSystems { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAcsSystems from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpAcsSystems { return new SeamHttpAcsSystems(constructorOptions) } + /** + * Creates a new SeamHttpAcsSystems authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpAcsSystems { return new SeamHttpAcsSystems(constructorOptions) } + /** + * Creates a new SeamHttpAcsSystems authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpAcsSystems { return new SeamHttpAcsSystems(constructorOptions) } + /** + * Creates a new SeamHttpAcsSystems authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -100,6 +117,10 @@ export class SeamHttpAcsSystems { return SeamHttpAcsSystems.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAcsSystems authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -117,6 +138,10 @@ export class SeamHttpAcsSystems { return new SeamHttpAcsSystems(constructorOptions) } + /** + * Creates a new SeamHttpAcsSystems authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -134,12 +159,21 @@ export class SeamHttpAcsSystems { return new SeamHttpAcsSystems(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/acs/users/users.ts b/src/lib/routes/acs/users/users.ts index 72a2bc78..48284482 100644 --- a/src/lib/routes/acs/users/users.ts +++ b/src/lib/routes/acs/users/users.ts @@ -38,6 +38,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /acs/users routes. + */ export class SeamHttpAcsUsers { client: Client readonly defaults: Required @@ -48,6 +51,9 @@ export class SeamHttpAcsUsers { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpAcsUsers from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -59,6 +65,9 @@ export class SeamHttpAcsUsers { return new SeamHttpAcsUsers(constructorOptions) } + /** + * Creates a new SeamHttpAcsUsers authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -70,6 +79,9 @@ export class SeamHttpAcsUsers { return new SeamHttpAcsUsers(constructorOptions) } + /** + * Creates a new SeamHttpAcsUsers authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -84,6 +96,11 @@ export class SeamHttpAcsUsers { return new SeamHttpAcsUsers(constructorOptions) } + /** + * Creates a new SeamHttpAcsUsers authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -104,6 +121,10 @@ export class SeamHttpAcsUsers { return SeamHttpAcsUsers.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpAcsUsers authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -121,6 +142,10 @@ export class SeamHttpAcsUsers { return new SeamHttpAcsUsers(constructorOptions) } + /** + * Creates a new SeamHttpAcsUsers authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -138,12 +163,21 @@ export class SeamHttpAcsUsers { return new SeamHttpAcsUsers(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/action-attempts/action-attempts.ts b/src/lib/routes/action-attempts/action-attempts.ts index d38d6852..b6497347 100644 --- a/src/lib/routes/action-attempts/action-attempts.ts +++ b/src/lib/routes/action-attempts/action-attempts.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /action_attempts routes. + */ export class SeamHttpActionAttempts { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpActionAttempts { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpActionAttempts from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpActionAttempts { return new SeamHttpActionAttempts(constructorOptions) } + /** + * Creates a new SeamHttpActionAttempts authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpActionAttempts { return new SeamHttpActionAttempts(constructorOptions) } + /** + * Creates a new SeamHttpActionAttempts authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpActionAttempts { return new SeamHttpActionAttempts(constructorOptions) } + /** + * Creates a new SeamHttpActionAttempts authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -100,6 +117,10 @@ export class SeamHttpActionAttempts { return SeamHttpActionAttempts.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpActionAttempts authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -117,6 +138,10 @@ export class SeamHttpActionAttempts { return new SeamHttpActionAttempts(constructorOptions) } + /** + * Creates a new SeamHttpActionAttempts authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -134,12 +159,21 @@ export class SeamHttpActionAttempts { return new SeamHttpActionAttempts(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/client-sessions/client-sessions.ts b/src/lib/routes/client-sessions/client-sessions.ts index 287e4356..e9216401 100644 --- a/src/lib/routes/client-sessions/client-sessions.ts +++ b/src/lib/routes/client-sessions/client-sessions.ts @@ -36,6 +36,9 @@ import type { ClientSession } from 'lib/resources/client-session.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /client_sessions routes. + */ export class SeamHttpClientSessions { client: Client readonly defaults: Required @@ -46,6 +49,9 @@ export class SeamHttpClientSessions { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpClientSessions from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -57,6 +63,9 @@ export class SeamHttpClientSessions { return new SeamHttpClientSessions(constructorOptions) } + /** + * Creates a new SeamHttpClientSessions authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -68,6 +77,9 @@ export class SeamHttpClientSessions { return new SeamHttpClientSessions(constructorOptions) } + /** + * Creates a new SeamHttpClientSessions authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -82,6 +94,11 @@ export class SeamHttpClientSessions { return new SeamHttpClientSessions(constructorOptions) } + /** + * Creates a new SeamHttpClientSessions authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -102,6 +119,10 @@ export class SeamHttpClientSessions { return SeamHttpClientSessions.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpClientSessions authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -119,6 +140,10 @@ export class SeamHttpClientSessions { return new SeamHttpClientSessions(constructorOptions) } + /** + * Creates a new SeamHttpClientSessions authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -136,12 +161,21 @@ export class SeamHttpClientSessions { return new SeamHttpClientSessions(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -340,6 +374,7 @@ export type ClientSessionsCreateParameters = { user_identity_id?: string | undefined /** * IDs of the [user identities](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) that you want to associate with the client session. + * * @deprecated Use `user_identity_id` instead. */ user_identity_ids?: Array | undefined @@ -419,6 +454,7 @@ export type ClientSessionsGetOrCreateParameters = { user_identity_id?: string | undefined /** * IDs of the [user identities](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) that you want to associate with the client session. + * * @deprecated Use `user_identity_id`. */ user_identity_ids?: Array | undefined @@ -461,6 +497,7 @@ export type ClientSessionsGrantAccessParameters = RequireAtLeastOne<{ user_identity_id?: string | undefined /** * IDs of the [user identities](https://docs.seam.co/capability-guides/mobile-access/managing-mobile-app-user-accounts-with-user-identities#what-is-a-user-identity) that you want to associate with the client session. + * * @deprecated Use `user_identity_id`. */ user_identity_ids?: Array | undefined diff --git a/src/lib/routes/connect-webviews/connect-webviews.ts b/src/lib/routes/connect-webviews/connect-webviews.ts index f5469d0b..eddcba69 100644 --- a/src/lib/routes/connect-webviews/connect-webviews.ts +++ b/src/lib/routes/connect-webviews/connect-webviews.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /connect_webviews routes. + */ export class SeamHttpConnectWebviews { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpConnectWebviews { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpConnectWebviews from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpConnectWebviews { return new SeamHttpConnectWebviews(constructorOptions) } + /** + * Creates a new SeamHttpConnectWebviews authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpConnectWebviews { return new SeamHttpConnectWebviews(constructorOptions) } + /** + * Creates a new SeamHttpConnectWebviews authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpConnectWebviews { return new SeamHttpConnectWebviews(constructorOptions) } + /** + * Creates a new SeamHttpConnectWebviews authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -100,6 +117,10 @@ export class SeamHttpConnectWebviews { return SeamHttpConnectWebviews.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpConnectWebviews authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -117,6 +138,10 @@ export class SeamHttpConnectWebviews { return new SeamHttpConnectWebviews(constructorOptions) } + /** + * Creates a new SeamHttpConnectWebviews authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -134,12 +159,21 @@ export class SeamHttpConnectWebviews { return new SeamHttpConnectWebviews(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/connected-accounts/connected-accounts.ts b/src/lib/routes/connected-accounts/connected-accounts.ts index 2c27c6ef..560dca73 100644 --- a/src/lib/routes/connected-accounts/connected-accounts.ts +++ b/src/lib/routes/connected-accounts/connected-accounts.ts @@ -39,6 +39,9 @@ import { SeamPaginator } from 'lib/seam-paginator.js' import { SeamHttpConnectedAccountsSimulate } from './simulate/index.js' +/** + * Client for the Seam API /connected_accounts routes. + */ export class SeamHttpConnectedAccounts { client: Client readonly defaults: Required @@ -49,6 +52,9 @@ export class SeamHttpConnectedAccounts { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpConnectedAccounts from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -60,6 +66,9 @@ export class SeamHttpConnectedAccounts { return new SeamHttpConnectedAccounts(constructorOptions) } + /** + * Creates a new SeamHttpConnectedAccounts authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -71,6 +80,9 @@ export class SeamHttpConnectedAccounts { return new SeamHttpConnectedAccounts(constructorOptions) } + /** + * Creates a new SeamHttpConnectedAccounts authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -85,6 +97,11 @@ export class SeamHttpConnectedAccounts { return new SeamHttpConnectedAccounts(constructorOptions) } + /** + * Creates a new SeamHttpConnectedAccounts authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -105,6 +122,10 @@ export class SeamHttpConnectedAccounts { return SeamHttpConnectedAccounts.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpConnectedAccounts authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -122,6 +143,10 @@ export class SeamHttpConnectedAccounts { return new SeamHttpConnectedAccounts(constructorOptions) } + /** + * Creates a new SeamHttpConnectedAccounts authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -139,12 +164,21 @@ export class SeamHttpConnectedAccounts { return new SeamHttpConnectedAccounts(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -164,6 +198,9 @@ export class SeamHttpConnectedAccounts { await clientSessions.get() } + /** + * Client for the Seam API /connected_accounts/simulate routes. + */ get simulate(): SeamHttpConnectedAccountsSimulate { return SeamHttpConnectedAccountsSimulate.fromClient( this.client, diff --git a/src/lib/routes/connected-accounts/simulate/simulate.ts b/src/lib/routes/connected-accounts/simulate/simulate.ts index c2e9abdd..11e76396 100644 --- a/src/lib/routes/connected-accounts/simulate/simulate.ts +++ b/src/lib/routes/connected-accounts/simulate/simulate.ts @@ -33,6 +33,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /connected_accounts/simulate routes. + */ export class SeamHttpConnectedAccountsSimulate { client: Client readonly defaults: Required @@ -43,6 +46,9 @@ export class SeamHttpConnectedAccountsSimulate { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpConnectedAccountsSimulate from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -54,6 +60,9 @@ export class SeamHttpConnectedAccountsSimulate { return new SeamHttpConnectedAccountsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpConnectedAccountsSimulate authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -65,6 +74,9 @@ export class SeamHttpConnectedAccountsSimulate { return new SeamHttpConnectedAccountsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpConnectedAccountsSimulate authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -79,6 +91,11 @@ export class SeamHttpConnectedAccountsSimulate { return new SeamHttpConnectedAccountsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpConnectedAccountsSimulate authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -102,6 +119,10 @@ export class SeamHttpConnectedAccountsSimulate { ) } + /** + * Creates a new SeamHttpConnectedAccountsSimulate authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -119,6 +140,10 @@ export class SeamHttpConnectedAccountsSimulate { return new SeamHttpConnectedAccountsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpConnectedAccountsSimulate authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -136,12 +161,21 @@ export class SeamHttpConnectedAccountsSimulate { return new SeamHttpConnectedAccountsSimulate(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/customers/customers.ts b/src/lib/routes/customers/customers.ts index fff611eb..7d2eea24 100644 --- a/src/lib/routes/customers/customers.ts +++ b/src/lib/routes/customers/customers.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /customers routes. + */ export class SeamHttpCustomers { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpCustomers { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpCustomers from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpCustomers { return new SeamHttpCustomers(constructorOptions) } + /** + * Creates a new SeamHttpCustomers authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpCustomers { return new SeamHttpCustomers(constructorOptions) } + /** + * Creates a new SeamHttpCustomers authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpCustomers { return new SeamHttpCustomers(constructorOptions) } + /** + * Creates a new SeamHttpCustomers authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -100,6 +117,10 @@ export class SeamHttpCustomers { return SeamHttpCustomers.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpCustomers authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -117,6 +138,10 @@ export class SeamHttpCustomers { return new SeamHttpCustomers(constructorOptions) } + /** + * Creates a new SeamHttpCustomers authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -134,12 +159,21 @@ export class SeamHttpCustomers { return new SeamHttpCustomers(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/devices/devices.ts b/src/lib/routes/devices/devices.ts index e00550cd..92283001 100644 --- a/src/lib/routes/devices/devices.ts +++ b/src/lib/routes/devices/devices.ts @@ -41,6 +41,9 @@ import { SeamPaginator } from 'lib/seam-paginator.js' import { SeamHttpDevicesSimulate } from './simulate/index.js' import { SeamHttpDevicesUnmanaged } from './unmanaged/index.js' +/** + * Client for the Seam API /devices routes. + */ export class SeamHttpDevices { client: Client readonly defaults: Required @@ -51,6 +54,9 @@ export class SeamHttpDevices { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpDevices from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -62,6 +68,9 @@ export class SeamHttpDevices { return new SeamHttpDevices(constructorOptions) } + /** + * Creates a new SeamHttpDevices authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -73,6 +82,9 @@ export class SeamHttpDevices { return new SeamHttpDevices(constructorOptions) } + /** + * Creates a new SeamHttpDevices authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -87,6 +99,11 @@ export class SeamHttpDevices { return new SeamHttpDevices(constructorOptions) } + /** + * Creates a new SeamHttpDevices authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -107,6 +124,10 @@ export class SeamHttpDevices { return SeamHttpDevices.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpDevices authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -124,6 +145,10 @@ export class SeamHttpDevices { return new SeamHttpDevices(constructorOptions) } + /** + * Creates a new SeamHttpDevices authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -141,12 +166,21 @@ export class SeamHttpDevices { return new SeamHttpDevices(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -166,10 +200,16 @@ export class SeamHttpDevices { await clientSessions.get() } + /** + * Client for the Seam API /devices/simulate routes. + */ get simulate(): SeamHttpDevicesSimulate { return SeamHttpDevicesSimulate.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /devices/unmanaged routes. + */ get unmanaged(): SeamHttpDevicesUnmanaged { return SeamHttpDevicesUnmanaged.fromClient(this.client, this.defaults) } diff --git a/src/lib/routes/devices/simulate/simulate.ts b/src/lib/routes/devices/simulate/simulate.ts index d8e07aab..280541e5 100644 --- a/src/lib/routes/devices/simulate/simulate.ts +++ b/src/lib/routes/devices/simulate/simulate.ts @@ -33,6 +33,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /devices/simulate routes. + */ export class SeamHttpDevicesSimulate { client: Client readonly defaults: Required @@ -43,6 +46,9 @@ export class SeamHttpDevicesSimulate { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpDevicesSimulate from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -54,6 +60,9 @@ export class SeamHttpDevicesSimulate { return new SeamHttpDevicesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpDevicesSimulate authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -65,6 +74,9 @@ export class SeamHttpDevicesSimulate { return new SeamHttpDevicesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpDevicesSimulate authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -79,6 +91,11 @@ export class SeamHttpDevicesSimulate { return new SeamHttpDevicesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpDevicesSimulate authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -99,6 +116,10 @@ export class SeamHttpDevicesSimulate { return SeamHttpDevicesSimulate.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpDevicesSimulate authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -116,6 +137,10 @@ export class SeamHttpDevicesSimulate { return new SeamHttpDevicesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpDevicesSimulate authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -133,12 +158,21 @@ export class SeamHttpDevicesSimulate { return new SeamHttpDevicesSimulate(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/devices/unmanaged/unmanaged.ts b/src/lib/routes/devices/unmanaged/unmanaged.ts index 3a9df460..1cce0cf0 100644 --- a/src/lib/routes/devices/unmanaged/unmanaged.ts +++ b/src/lib/routes/devices/unmanaged/unmanaged.ts @@ -37,6 +37,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /devices/unmanaged routes. + */ export class SeamHttpDevicesUnmanaged { client: Client readonly defaults: Required @@ -47,6 +50,9 @@ export class SeamHttpDevicesUnmanaged { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpDevicesUnmanaged from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -58,6 +64,9 @@ export class SeamHttpDevicesUnmanaged { return new SeamHttpDevicesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpDevicesUnmanaged authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -69,6 +78,9 @@ export class SeamHttpDevicesUnmanaged { return new SeamHttpDevicesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpDevicesUnmanaged authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -83,6 +95,11 @@ export class SeamHttpDevicesUnmanaged { return new SeamHttpDevicesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpDevicesUnmanaged authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -103,6 +120,10 @@ export class SeamHttpDevicesUnmanaged { return SeamHttpDevicesUnmanaged.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpDevicesUnmanaged authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -120,6 +141,10 @@ export class SeamHttpDevicesUnmanaged { return new SeamHttpDevicesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpDevicesUnmanaged authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -137,12 +162,21 @@ export class SeamHttpDevicesUnmanaged { return new SeamHttpDevicesUnmanaged(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/events/events.ts b/src/lib/routes/events/events.ts index 653cf2e7..01eaa689 100644 --- a/src/lib/routes/events/events.ts +++ b/src/lib/routes/events/events.ts @@ -37,6 +37,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /events routes. + */ export class SeamHttpEvents { client: Client readonly defaults: Required @@ -47,6 +50,9 @@ export class SeamHttpEvents { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpEvents from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -58,6 +64,9 @@ export class SeamHttpEvents { return new SeamHttpEvents(constructorOptions) } + /** + * Creates a new SeamHttpEvents authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -69,6 +78,9 @@ export class SeamHttpEvents { return new SeamHttpEvents(constructorOptions) } + /** + * Creates a new SeamHttpEvents authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -83,6 +95,11 @@ export class SeamHttpEvents { return new SeamHttpEvents(constructorOptions) } + /** + * Creates a new SeamHttpEvents authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -103,6 +120,10 @@ export class SeamHttpEvents { return SeamHttpEvents.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpEvents authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -120,6 +141,10 @@ export class SeamHttpEvents { return new SeamHttpEvents(constructorOptions) } + /** + * Creates a new SeamHttpEvents authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -137,12 +162,21 @@ export class SeamHttpEvents { return new SeamHttpEvents(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/instant-keys/instant-keys.ts b/src/lib/routes/instant-keys/instant-keys.ts index e58985da..63576c76 100644 --- a/src/lib/routes/instant-keys/instant-keys.ts +++ b/src/lib/routes/instant-keys/instant-keys.ts @@ -37,6 +37,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /instant_keys routes. + */ export class SeamHttpInstantKeys { client: Client readonly defaults: Required @@ -47,6 +50,9 @@ export class SeamHttpInstantKeys { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpInstantKeys from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -58,6 +64,9 @@ export class SeamHttpInstantKeys { return new SeamHttpInstantKeys(constructorOptions) } + /** + * Creates a new SeamHttpInstantKeys authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -69,6 +78,9 @@ export class SeamHttpInstantKeys { return new SeamHttpInstantKeys(constructorOptions) } + /** + * Creates a new SeamHttpInstantKeys authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -83,6 +95,11 @@ export class SeamHttpInstantKeys { return new SeamHttpInstantKeys(constructorOptions) } + /** + * Creates a new SeamHttpInstantKeys authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -103,6 +120,10 @@ export class SeamHttpInstantKeys { return SeamHttpInstantKeys.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpInstantKeys authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -120,6 +141,10 @@ export class SeamHttpInstantKeys { return new SeamHttpInstantKeys(constructorOptions) } + /** + * Creates a new SeamHttpInstantKeys authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -137,12 +162,21 @@ export class SeamHttpInstantKeys { return new SeamHttpInstantKeys(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/locks/locks.ts b/src/lib/routes/locks/locks.ts index 2b49c47d..8f1bcc12 100644 --- a/src/lib/routes/locks/locks.ts +++ b/src/lib/routes/locks/locks.ts @@ -41,6 +41,9 @@ import { SeamPaginator } from 'lib/seam-paginator.js' import { SeamHttpLocksSimulate } from './simulate/index.js' +/** + * Client for the Seam API /locks routes. + */ export class SeamHttpLocks { client: Client readonly defaults: Required @@ -51,6 +54,9 @@ export class SeamHttpLocks { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpLocks from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -62,6 +68,9 @@ export class SeamHttpLocks { return new SeamHttpLocks(constructorOptions) } + /** + * Creates a new SeamHttpLocks authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -73,6 +82,9 @@ export class SeamHttpLocks { return new SeamHttpLocks(constructorOptions) } + /** + * Creates a new SeamHttpLocks authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -87,6 +99,11 @@ export class SeamHttpLocks { return new SeamHttpLocks(constructorOptions) } + /** + * Creates a new SeamHttpLocks authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -107,6 +124,10 @@ export class SeamHttpLocks { return SeamHttpLocks.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpLocks authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -124,6 +145,10 @@ export class SeamHttpLocks { return new SeamHttpLocks(constructorOptions) } + /** + * Creates a new SeamHttpLocks authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -141,12 +166,21 @@ export class SeamHttpLocks { return new SeamHttpLocks(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -166,6 +200,9 @@ export class SeamHttpLocks { await clientSessions.get() } + /** + * Client for the Seam API /locks/simulate routes. + */ get simulate(): SeamHttpLocksSimulate { return SeamHttpLocksSimulate.fromClient(this.client, this.defaults) } @@ -199,6 +236,7 @@ export class SeamHttpLocks { /** * Returns a specified [lock](https://docs.seam.co/low-level-apis/smart-locks). + * * @deprecated Use `/devices/get` instead. */ get( diff --git a/src/lib/routes/locks/simulate/simulate.ts b/src/lib/routes/locks/simulate/simulate.ts index 109a9dfa..1082c506 100644 --- a/src/lib/routes/locks/simulate/simulate.ts +++ b/src/lib/routes/locks/simulate/simulate.ts @@ -35,6 +35,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /locks/simulate routes. + */ export class SeamHttpLocksSimulate { client: Client readonly defaults: Required @@ -45,6 +48,9 @@ export class SeamHttpLocksSimulate { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpLocksSimulate from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -56,6 +62,9 @@ export class SeamHttpLocksSimulate { return new SeamHttpLocksSimulate(constructorOptions) } + /** + * Creates a new SeamHttpLocksSimulate authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -67,6 +76,9 @@ export class SeamHttpLocksSimulate { return new SeamHttpLocksSimulate(constructorOptions) } + /** + * Creates a new SeamHttpLocksSimulate authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -81,6 +93,11 @@ export class SeamHttpLocksSimulate { return new SeamHttpLocksSimulate(constructorOptions) } + /** + * Creates a new SeamHttpLocksSimulate authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -101,6 +118,10 @@ export class SeamHttpLocksSimulate { return SeamHttpLocksSimulate.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpLocksSimulate authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -118,6 +139,10 @@ export class SeamHttpLocksSimulate { return new SeamHttpLocksSimulate(constructorOptions) } + /** + * Creates a new SeamHttpLocksSimulate authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -135,12 +160,21 @@ export class SeamHttpLocksSimulate { return new SeamHttpLocksSimulate(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/noise-sensors/noise-sensors.ts b/src/lib/routes/noise-sensors/noise-sensors.ts index 1ebf8f1a..fe9d242f 100644 --- a/src/lib/routes/noise-sensors/noise-sensors.ts +++ b/src/lib/routes/noise-sensors/noise-sensors.ts @@ -37,6 +37,9 @@ import { SeamPaginator } from 'lib/seam-paginator.js' import { SeamHttpNoiseSensorsNoiseThresholds } from './noise-thresholds/index.js' import { SeamHttpNoiseSensorsSimulate } from './simulate/index.js' +/** + * Client for the Seam API /noise_sensors routes. + */ export class SeamHttpNoiseSensors { client: Client readonly defaults: Required @@ -47,6 +50,9 @@ export class SeamHttpNoiseSensors { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpNoiseSensors from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -58,6 +64,9 @@ export class SeamHttpNoiseSensors { return new SeamHttpNoiseSensors(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensors authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -69,6 +78,9 @@ export class SeamHttpNoiseSensors { return new SeamHttpNoiseSensors(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensors authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -83,6 +95,11 @@ export class SeamHttpNoiseSensors { return new SeamHttpNoiseSensors(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensors authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -103,6 +120,10 @@ export class SeamHttpNoiseSensors { return SeamHttpNoiseSensors.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpNoiseSensors authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -120,6 +141,10 @@ export class SeamHttpNoiseSensors { return new SeamHttpNoiseSensors(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensors authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -137,12 +162,21 @@ export class SeamHttpNoiseSensors { return new SeamHttpNoiseSensors(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -162,6 +196,9 @@ export class SeamHttpNoiseSensors { await clientSessions.get() } + /** + * Client for the Seam API /noise_sensors/noise_thresholds routes. + */ get noiseThresholds(): SeamHttpNoiseSensorsNoiseThresholds { return SeamHttpNoiseSensorsNoiseThresholds.fromClient( this.client, @@ -169,6 +206,9 @@ export class SeamHttpNoiseSensors { ) } + /** + * Client for the Seam API /noise_sensors/simulate routes. + */ get simulate(): SeamHttpNoiseSensorsSimulate { return SeamHttpNoiseSensorsSimulate.fromClient(this.client, this.defaults) } diff --git a/src/lib/routes/noise-sensors/noise-thresholds/noise-thresholds.ts b/src/lib/routes/noise-sensors/noise-thresholds/noise-thresholds.ts index 2c0a37f1..db900f68 100644 --- a/src/lib/routes/noise-sensors/noise-thresholds/noise-thresholds.ts +++ b/src/lib/routes/noise-sensors/noise-thresholds/noise-thresholds.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /noise_sensors/noise_thresholds routes. + */ export class SeamHttpNoiseSensorsNoiseThresholds { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpNoiseSensorsNoiseThresholds { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpNoiseSensorsNoiseThresholds from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpNoiseSensorsNoiseThresholds { return new SeamHttpNoiseSensorsNoiseThresholds(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensorsNoiseThresholds authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpNoiseSensorsNoiseThresholds { return new SeamHttpNoiseSensorsNoiseThresholds(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensorsNoiseThresholds authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpNoiseSensorsNoiseThresholds { return new SeamHttpNoiseSensorsNoiseThresholds(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensorsNoiseThresholds authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -103,6 +120,10 @@ export class SeamHttpNoiseSensorsNoiseThresholds { ) } + /** + * Creates a new SeamHttpNoiseSensorsNoiseThresholds authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -120,6 +141,10 @@ export class SeamHttpNoiseSensorsNoiseThresholds { return new SeamHttpNoiseSensorsNoiseThresholds(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensorsNoiseThresholds authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -137,12 +162,21 @@ export class SeamHttpNoiseSensorsNoiseThresholds { return new SeamHttpNoiseSensorsNoiseThresholds(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/noise-sensors/simulate/simulate.ts b/src/lib/routes/noise-sensors/simulate/simulate.ts index f2666bc3..f50f94c7 100644 --- a/src/lib/routes/noise-sensors/simulate/simulate.ts +++ b/src/lib/routes/noise-sensors/simulate/simulate.ts @@ -33,6 +33,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /noise_sensors/simulate routes. + */ export class SeamHttpNoiseSensorsSimulate { client: Client readonly defaults: Required @@ -43,6 +46,9 @@ export class SeamHttpNoiseSensorsSimulate { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpNoiseSensorsSimulate from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -54,6 +60,9 @@ export class SeamHttpNoiseSensorsSimulate { return new SeamHttpNoiseSensorsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensorsSimulate authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -65,6 +74,9 @@ export class SeamHttpNoiseSensorsSimulate { return new SeamHttpNoiseSensorsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensorsSimulate authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -79,6 +91,11 @@ export class SeamHttpNoiseSensorsSimulate { return new SeamHttpNoiseSensorsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensorsSimulate authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -99,6 +116,10 @@ export class SeamHttpNoiseSensorsSimulate { return SeamHttpNoiseSensorsSimulate.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpNoiseSensorsSimulate authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -116,6 +137,10 @@ export class SeamHttpNoiseSensorsSimulate { return new SeamHttpNoiseSensorsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpNoiseSensorsSimulate authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -133,12 +158,21 @@ export class SeamHttpNoiseSensorsSimulate { return new SeamHttpNoiseSensorsSimulate(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/phones/phones.ts b/src/lib/routes/phones/phones.ts index 4400ed5b..0ce10b90 100644 --- a/src/lib/routes/phones/phones.ts +++ b/src/lib/routes/phones/phones.ts @@ -36,6 +36,9 @@ import { SeamPaginator } from 'lib/seam-paginator.js' import { SeamHttpPhonesSimulate } from './simulate/index.js' +/** + * Client for the Seam API /phones routes. + */ export class SeamHttpPhones { client: Client readonly defaults: Required @@ -46,6 +49,9 @@ export class SeamHttpPhones { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpPhones from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -57,6 +63,9 @@ export class SeamHttpPhones { return new SeamHttpPhones(constructorOptions) } + /** + * Creates a new SeamHttpPhones authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -68,6 +77,9 @@ export class SeamHttpPhones { return new SeamHttpPhones(constructorOptions) } + /** + * Creates a new SeamHttpPhones authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -82,6 +94,11 @@ export class SeamHttpPhones { return new SeamHttpPhones(constructorOptions) } + /** + * Creates a new SeamHttpPhones authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -102,6 +119,10 @@ export class SeamHttpPhones { return SeamHttpPhones.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpPhones authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -119,6 +140,10 @@ export class SeamHttpPhones { return new SeamHttpPhones(constructorOptions) } + /** + * Creates a new SeamHttpPhones authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -136,12 +161,21 @@ export class SeamHttpPhones { return new SeamHttpPhones(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -161,6 +195,9 @@ export class SeamHttpPhones { await clientSessions.get() } + /** + * Client for the Seam API /phones/simulate routes. + */ get simulate(): SeamHttpPhonesSimulate { return SeamHttpPhonesSimulate.fromClient(this.client, this.defaults) } diff --git a/src/lib/routes/phones/simulate/simulate.ts b/src/lib/routes/phones/simulate/simulate.ts index 05965c07..6b5e2797 100644 --- a/src/lib/routes/phones/simulate/simulate.ts +++ b/src/lib/routes/phones/simulate/simulate.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /phones/simulate routes. + */ export class SeamHttpPhonesSimulate { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpPhonesSimulate { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpPhonesSimulate from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpPhonesSimulate { return new SeamHttpPhonesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpPhonesSimulate authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpPhonesSimulate { return new SeamHttpPhonesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpPhonesSimulate authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpPhonesSimulate { return new SeamHttpPhonesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpPhonesSimulate authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -100,6 +117,10 @@ export class SeamHttpPhonesSimulate { return SeamHttpPhonesSimulate.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpPhonesSimulate authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -117,6 +138,10 @@ export class SeamHttpPhonesSimulate { return new SeamHttpPhonesSimulate(constructorOptions) } + /** + * Creates a new SeamHttpPhonesSimulate authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -134,12 +159,21 @@ export class SeamHttpPhonesSimulate { return new SeamHttpPhonesSimulate(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/seam-http-endpoints-without-workspace.ts b/src/lib/routes/seam-http-endpoints-without-workspace.ts index d27ffa1e..9f661eba 100644 --- a/src/lib/routes/seam-http-endpoints-without-workspace.ts +++ b/src/lib/routes/seam-http-endpoints-without-workspace.ts @@ -30,6 +30,10 @@ import { type WorkspacesListRequest, } from './workspaces/index.js' +/** + * HTTP client for the Seam API not scoped to a workspace + * with endpoints keyed by their path, e.g., `seam.get['/devices/list']()`. + */ export class SeamHttpEndpointsWithoutWorkspace { client: Client readonly defaults: Required @@ -40,6 +44,9 @@ export class SeamHttpEndpointsWithoutWorkspace { this.defaults = limitToSeamHttpRequestOptions(opts) } + /** + * Creates a new SeamHttpEndpointsWithoutWorkspace from an existing HTTP client. + */ static fromClient( client: SeamHttpWithoutWorkspaceOptionsWithClient['client'], options: Omit = {}, @@ -51,6 +58,10 @@ export class SeamHttpEndpointsWithoutWorkspace { return new SeamHttpEndpointsWithoutWorkspace(constructorOptions) } + /** + * Creates a new SeamHttpEndpointsWithoutWorkspace authenticated with a console session token + * and not scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken['consoleSessionToken'], options: Omit< @@ -71,6 +82,10 @@ export class SeamHttpEndpointsWithoutWorkspace { return new SeamHttpEndpointsWithoutWorkspace(constructorOptions) } + /** + * Creates a new SeamHttpEndpointsWithoutWorkspace authenticated with a personal access token + * and not scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken['personalAccessToken'], options: Omit< diff --git a/src/lib/routes/seam-http-endpoints.ts b/src/lib/routes/seam-http-endpoints.ts index ed260485..c9324353 100644 --- a/src/lib/routes/seam-http-endpoints.ts +++ b/src/lib/routes/seam-http-endpoints.ts @@ -758,6 +758,10 @@ import { type WorkspacesUpdateRequest, } from './workspaces/index.js' +/** + * HTTP client for the Seam API + * with endpoints keyed by their path, e.g., `seam.get['/devices/list']()`. + */ export class SeamHttpEndpoints { client: Client readonly defaults: Required @@ -768,6 +772,9 @@ export class SeamHttpEndpoints { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpEndpoints from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -779,6 +786,9 @@ export class SeamHttpEndpoints { return new SeamHttpEndpoints(constructorOptions) } + /** + * Creates a new SeamHttpEndpoints authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -790,6 +800,9 @@ export class SeamHttpEndpoints { return new SeamHttpEndpoints(constructorOptions) } + /** + * Creates a new SeamHttpEndpoints authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -804,6 +817,11 @@ export class SeamHttpEndpoints { return new SeamHttpEndpoints(constructorOptions) } + /** + * Creates a new SeamHttpEndpoints authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -824,6 +842,10 @@ export class SeamHttpEndpoints { return SeamHttpEndpoints.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpEndpoints authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -841,6 +863,10 @@ export class SeamHttpEndpoints { return new SeamHttpEndpoints(constructorOptions) } + /** + * Creates a new SeamHttpEndpoints authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -858,12 +884,21 @@ export class SeamHttpEndpoints { return new SeamHttpEndpoints(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -2928,6 +2963,7 @@ export class SeamHttpEndpoints { /** * Returns a specified [lock](https://docs.seam.co/low-level-apis/smart-locks). + * * @deprecated Use `/devices/get` instead. */ get '/locks/get'(): ( diff --git a/src/lib/routes/seam-http-without-workspace.ts b/src/lib/routes/seam-http-without-workspace.ts index 08aee457..87054cc5 100644 --- a/src/lib/routes/seam-http-without-workspace.ts +++ b/src/lib/routes/seam-http-without-workspace.ts @@ -21,6 +21,13 @@ import { } from 'lib/parse-options.js' import { SeamHttpWorkspaces } from 'lib/routes/workspaces/index.js' +/** + * HTTP client for the Seam API not scoped to a workspace. + * + * Use this client to list or create workspaces, + * e.g., when authenticated with a personal access token + * or console session token. + */ export class SeamHttpWithoutWorkspace { client: Client readonly defaults: Required @@ -31,6 +38,9 @@ export class SeamHttpWithoutWorkspace { this.defaults = limitToSeamHttpRequestOptions(opts) } + /** + * Creates a new SeamHttpWithoutWorkspace from an existing HTTP client. + */ static fromClient( client: SeamHttpWithoutWorkspaceOptionsWithClient['client'], options: Omit = {}, @@ -42,6 +52,10 @@ export class SeamHttpWithoutWorkspace { return new SeamHttpWithoutWorkspace(constructorOptions) } + /** + * Creates a new SeamHttpWithoutWorkspace authenticated with a console session token + * and not scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpWithoutWorkspaceOptionsWithConsoleSessionToken['consoleSessionToken'], options: Omit< @@ -62,6 +76,10 @@ export class SeamHttpWithoutWorkspace { return new SeamHttpWithoutWorkspace(constructorOptions) } + /** + * Creates a new SeamHttpWithoutWorkspace authenticated with a personal access token + * and not scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpWithoutWorkspaceOptionsWithPersonalAccessToken['personalAccessToken'], options: Omit< @@ -82,6 +100,9 @@ export class SeamHttpWithoutWorkspace { return new SeamHttpWithoutWorkspace(constructorOptions) } + /** + * Client for the Seam API /workspaces routes available without a workspace. + */ get workspaces(): Pick { return SeamHttpWorkspaces.fromClient(this.client, this.defaults) } diff --git a/src/lib/routes/seam-http.ts b/src/lib/routes/seam-http.ts index 8aeda6cf..1bce193a 100644 --- a/src/lib/routes/seam-http.ts +++ b/src/lib/routes/seam-http.ts @@ -52,6 +52,14 @@ import { SeamHttpUserIdentities } from './user-identities/index.js' import { SeamHttpWebhooks } from './webhooks/index.js' import { SeamHttpWorkspaces } from './workspaces/index.js' +/** + * HTTP client for the Seam API. + * + * Create a client with the constructor + * or one of the static factory methods, e.g., `fromApiKey`. + * Each Seam API route is available under its corresponding property, + * e.g., use `seam.devices.list()` to call the `/devices/list` endpoint. + */ export class SeamHttp { client: Client readonly defaults: Required @@ -62,6 +70,9 @@ export class SeamHttp { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttp from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -73,6 +84,9 @@ export class SeamHttp { return new SeamHttp(constructorOptions) } + /** + * Creates a new SeamHttp authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -84,6 +98,9 @@ export class SeamHttp { return new SeamHttp(constructorOptions) } + /** + * Creates a new SeamHttp authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -98,6 +115,11 @@ export class SeamHttp { return new SeamHttp(constructorOptions) } + /** + * Creates a new SeamHttp authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -118,6 +140,10 @@ export class SeamHttp { return SeamHttp.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttp authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -135,6 +161,10 @@ export class SeamHttp { return new SeamHttp(constructorOptions) } + /** + * Creates a new SeamHttp authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -152,12 +182,21 @@ export class SeamHttp { return new SeamHttp(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -177,82 +216,142 @@ export class SeamHttp { await clientSessions.get() } + /** + * Client for the Seam API /access_codes routes. + */ get accessCodes(): SeamHttpAccessCodes { return SeamHttpAccessCodes.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /access_grants routes. + */ get accessGrants(): SeamHttpAccessGrants { return SeamHttpAccessGrants.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /access_methods routes. + */ get accessMethods(): SeamHttpAccessMethods { return SeamHttpAccessMethods.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /acs routes. + */ get acs(): SeamHttpAcs { return SeamHttpAcs.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /action_attempts routes. + */ get actionAttempts(): SeamHttpActionAttempts { return SeamHttpActionAttempts.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /client_sessions routes. + */ get clientSessions(): SeamHttpClientSessions { return SeamHttpClientSessions.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /connect_webviews routes. + */ get connectWebviews(): SeamHttpConnectWebviews { return SeamHttpConnectWebviews.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /connected_accounts routes. + */ get connectedAccounts(): SeamHttpConnectedAccounts { return SeamHttpConnectedAccounts.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /customers routes. + */ get customers(): SeamHttpCustomers { return SeamHttpCustomers.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /devices routes. + */ get devices(): SeamHttpDevices { return SeamHttpDevices.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /events routes. + */ get events(): SeamHttpEvents { return SeamHttpEvents.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /instant_keys routes. + */ get instantKeys(): SeamHttpInstantKeys { return SeamHttpInstantKeys.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /locks routes. + */ get locks(): SeamHttpLocks { return SeamHttpLocks.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /noise_sensors routes. + */ get noiseSensors(): SeamHttpNoiseSensors { return SeamHttpNoiseSensors.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /phones routes. + */ get phones(): SeamHttpPhones { return SeamHttpPhones.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /spaces routes. + */ get spaces(): SeamHttpSpaces { return SeamHttpSpaces.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /thermostats routes. + */ get thermostats(): SeamHttpThermostats { return SeamHttpThermostats.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /user_identities routes. + */ get userIdentities(): SeamHttpUserIdentities { return SeamHttpUserIdentities.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /webhooks routes. + */ get webhooks(): SeamHttpWebhooks { return SeamHttpWebhooks.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /workspaces routes. + */ get workspaces(): SeamHttpWorkspaces { return SeamHttpWorkspaces.fromClient(this.client, this.defaults) } diff --git a/src/lib/routes/spaces/spaces.ts b/src/lib/routes/spaces/spaces.ts index 507d8190..3feab972 100644 --- a/src/lib/routes/spaces/spaces.ts +++ b/src/lib/routes/spaces/spaces.ts @@ -38,6 +38,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /spaces routes. + */ export class SeamHttpSpaces { client: Client readonly defaults: Required @@ -48,6 +51,9 @@ export class SeamHttpSpaces { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpSpaces from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -59,6 +65,9 @@ export class SeamHttpSpaces { return new SeamHttpSpaces(constructorOptions) } + /** + * Creates a new SeamHttpSpaces authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -70,6 +79,9 @@ export class SeamHttpSpaces { return new SeamHttpSpaces(constructorOptions) } + /** + * Creates a new SeamHttpSpaces authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -84,6 +96,11 @@ export class SeamHttpSpaces { return new SeamHttpSpaces(constructorOptions) } + /** + * Creates a new SeamHttpSpaces authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -104,6 +121,10 @@ export class SeamHttpSpaces { return SeamHttpSpaces.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpSpaces authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -121,6 +142,10 @@ export class SeamHttpSpaces { return new SeamHttpSpaces(constructorOptions) } + /** + * Creates a new SeamHttpSpaces authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -138,12 +163,21 @@ export class SeamHttpSpaces { return new SeamHttpSpaces(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/thermostats/daily-programs/daily-programs.ts b/src/lib/routes/thermostats/daily-programs/daily-programs.ts index 6cbab61e..9f1b608b 100644 --- a/src/lib/routes/thermostats/daily-programs/daily-programs.ts +++ b/src/lib/routes/thermostats/daily-programs/daily-programs.ts @@ -36,6 +36,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /thermostats/daily_programs routes. + */ export class SeamHttpThermostatsDailyPrograms { client: Client readonly defaults: Required @@ -46,6 +49,9 @@ export class SeamHttpThermostatsDailyPrograms { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpThermostatsDailyPrograms from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -57,6 +63,9 @@ export class SeamHttpThermostatsDailyPrograms { return new SeamHttpThermostatsDailyPrograms(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsDailyPrograms authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -68,6 +77,9 @@ export class SeamHttpThermostatsDailyPrograms { return new SeamHttpThermostatsDailyPrograms(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsDailyPrograms authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -82,6 +94,11 @@ export class SeamHttpThermostatsDailyPrograms { return new SeamHttpThermostatsDailyPrograms(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsDailyPrograms authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -105,6 +122,10 @@ export class SeamHttpThermostatsDailyPrograms { ) } + /** + * Creates a new SeamHttpThermostatsDailyPrograms authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -122,6 +143,10 @@ export class SeamHttpThermostatsDailyPrograms { return new SeamHttpThermostatsDailyPrograms(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsDailyPrograms authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -139,12 +164,21 @@ export class SeamHttpThermostatsDailyPrograms { return new SeamHttpThermostatsDailyPrograms(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/thermostats/schedules/schedules.ts b/src/lib/routes/thermostats/schedules/schedules.ts index bea1ced5..5fadd9aa 100644 --- a/src/lib/routes/thermostats/schedules/schedules.ts +++ b/src/lib/routes/thermostats/schedules/schedules.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /thermostats/schedules routes. + */ export class SeamHttpThermostatsSchedules { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpThermostatsSchedules { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpThermostatsSchedules from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpThermostatsSchedules { return new SeamHttpThermostatsSchedules(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsSchedules authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpThermostatsSchedules { return new SeamHttpThermostatsSchedules(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsSchedules authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpThermostatsSchedules { return new SeamHttpThermostatsSchedules(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsSchedules authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -100,6 +117,10 @@ export class SeamHttpThermostatsSchedules { return SeamHttpThermostatsSchedules.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpThermostatsSchedules authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -117,6 +138,10 @@ export class SeamHttpThermostatsSchedules { return new SeamHttpThermostatsSchedules(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsSchedules authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -134,12 +159,21 @@ export class SeamHttpThermostatsSchedules { return new SeamHttpThermostatsSchedules(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/thermostats/simulate/simulate.ts b/src/lib/routes/thermostats/simulate/simulate.ts index 3bcad89a..df8da7c9 100644 --- a/src/lib/routes/thermostats/simulate/simulate.ts +++ b/src/lib/routes/thermostats/simulate/simulate.ts @@ -33,6 +33,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /thermostats/simulate routes. + */ export class SeamHttpThermostatsSimulate { client: Client readonly defaults: Required @@ -43,6 +46,9 @@ export class SeamHttpThermostatsSimulate { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpThermostatsSimulate from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -54,6 +60,9 @@ export class SeamHttpThermostatsSimulate { return new SeamHttpThermostatsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsSimulate authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -65,6 +74,9 @@ export class SeamHttpThermostatsSimulate { return new SeamHttpThermostatsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsSimulate authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -79,6 +91,11 @@ export class SeamHttpThermostatsSimulate { return new SeamHttpThermostatsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsSimulate authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -99,6 +116,10 @@ export class SeamHttpThermostatsSimulate { return SeamHttpThermostatsSimulate.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpThermostatsSimulate authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -116,6 +137,10 @@ export class SeamHttpThermostatsSimulate { return new SeamHttpThermostatsSimulate(constructorOptions) } + /** + * Creates a new SeamHttpThermostatsSimulate authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -133,12 +158,21 @@ export class SeamHttpThermostatsSimulate { return new SeamHttpThermostatsSimulate(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/thermostats/thermostats.ts b/src/lib/routes/thermostats/thermostats.ts index d0be628d..93d7d678 100644 --- a/src/lib/routes/thermostats/thermostats.ts +++ b/src/lib/routes/thermostats/thermostats.ts @@ -40,6 +40,9 @@ import { SeamHttpThermostatsDailyPrograms } from './daily-programs/index.js' import { SeamHttpThermostatsSchedules } from './schedules/index.js' import { SeamHttpThermostatsSimulate } from './simulate/index.js' +/** + * Client for the Seam API /thermostats routes. + */ export class SeamHttpThermostats { client: Client readonly defaults: Required @@ -50,6 +53,9 @@ export class SeamHttpThermostats { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpThermostats from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -61,6 +67,9 @@ export class SeamHttpThermostats { return new SeamHttpThermostats(constructorOptions) } + /** + * Creates a new SeamHttpThermostats authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -72,6 +81,9 @@ export class SeamHttpThermostats { return new SeamHttpThermostats(constructorOptions) } + /** + * Creates a new SeamHttpThermostats authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -86,6 +98,11 @@ export class SeamHttpThermostats { return new SeamHttpThermostats(constructorOptions) } + /** + * Creates a new SeamHttpThermostats authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -106,6 +123,10 @@ export class SeamHttpThermostats { return SeamHttpThermostats.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpThermostats authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -123,6 +144,10 @@ export class SeamHttpThermostats { return new SeamHttpThermostats(constructorOptions) } + /** + * Creates a new SeamHttpThermostats authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -140,12 +165,21 @@ export class SeamHttpThermostats { return new SeamHttpThermostats(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -165,6 +199,9 @@ export class SeamHttpThermostats { await clientSessions.get() } + /** + * Client for the Seam API /thermostats/daily_programs routes. + */ get dailyPrograms(): SeamHttpThermostatsDailyPrograms { return SeamHttpThermostatsDailyPrograms.fromClient( this.client, @@ -172,10 +209,16 @@ export class SeamHttpThermostats { ) } + /** + * Client for the Seam API /thermostats/schedules routes. + */ get schedules(): SeamHttpThermostatsSchedules { return SeamHttpThermostatsSchedules.fromClient(this.client, this.defaults) } + /** + * Client for the Seam API /thermostats/simulate routes. + */ get simulate(): SeamHttpThermostatsSimulate { return SeamHttpThermostatsSimulate.fromClient(this.client, this.defaults) } @@ -638,6 +681,7 @@ export type ThermostatsCreateClimatePresetParameters = { hvac_mode_setting?: 'off' | 'heat' | 'cool' | 'heat_cool' | 'eco' | undefined /** * Indicates whether a person at the thermostat or using the API can change the thermostat's settings. + * * @deprecated Use 'thermostat_schedule.is_override_allowed' */ manual_override_allowed?: boolean | undefined @@ -869,6 +913,7 @@ export type ThermostatsSetFanModeParameters = { /** * Fan mode setting for the thermostat, such as `auto`, `on`, or `circulate`. + * * @deprecated Use `fan_mode_setting` instead. */ fan_mode?: 'auto' | 'on' | 'circulate' | undefined @@ -1031,6 +1076,7 @@ export type ThermostatsUpdateClimatePresetParameters = { hvac_mode_setting?: 'off' | 'heat' | 'cool' | 'heat_cool' | 'eco' | undefined /** * Indicates whether a person at the thermostat can change the thermostat's settings. See [Specifying Manual Override Permissions](https://docs.seam.co/capability-guides/thermostats/creating-and-managing-thermostat-schedules#specifying-manual-override-permissions). + * * @deprecated Use 'thermostat_schedule.is_override_allowed' */ manual_override_allowed?: boolean | undefined diff --git a/src/lib/routes/user-identities/unmanaged/unmanaged.ts b/src/lib/routes/user-identities/unmanaged/unmanaged.ts index 9bbc6522..c627c073 100644 --- a/src/lib/routes/user-identities/unmanaged/unmanaged.ts +++ b/src/lib/routes/user-identities/unmanaged/unmanaged.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /user_identities/unmanaged routes. + */ export class SeamHttpUserIdentitiesUnmanaged { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpUserIdentitiesUnmanaged { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpUserIdentitiesUnmanaged from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpUserIdentitiesUnmanaged { return new SeamHttpUserIdentitiesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpUserIdentitiesUnmanaged authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpUserIdentitiesUnmanaged { return new SeamHttpUserIdentitiesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpUserIdentitiesUnmanaged authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpUserIdentitiesUnmanaged { return new SeamHttpUserIdentitiesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpUserIdentitiesUnmanaged authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -103,6 +120,10 @@ export class SeamHttpUserIdentitiesUnmanaged { ) } + /** + * Creates a new SeamHttpUserIdentitiesUnmanaged authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -120,6 +141,10 @@ export class SeamHttpUserIdentitiesUnmanaged { return new SeamHttpUserIdentitiesUnmanaged(constructorOptions) } + /** + * Creates a new SeamHttpUserIdentitiesUnmanaged authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -137,12 +162,21 @@ export class SeamHttpUserIdentitiesUnmanaged { return new SeamHttpUserIdentitiesUnmanaged(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/user-identities/user-identities.ts b/src/lib/routes/user-identities/user-identities.ts index 8af4bb64..d196c483 100644 --- a/src/lib/routes/user-identities/user-identities.ts +++ b/src/lib/routes/user-identities/user-identities.ts @@ -44,6 +44,9 @@ import { SeamPaginator } from 'lib/seam-paginator.js' import { SeamHttpUserIdentitiesUnmanaged } from './unmanaged/index.js' +/** + * Client for the Seam API /user_identities routes. + */ export class SeamHttpUserIdentities { client: Client readonly defaults: Required @@ -54,6 +57,9 @@ export class SeamHttpUserIdentities { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpUserIdentities from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -65,6 +71,9 @@ export class SeamHttpUserIdentities { return new SeamHttpUserIdentities(constructorOptions) } + /** + * Creates a new SeamHttpUserIdentities authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -76,6 +85,9 @@ export class SeamHttpUserIdentities { return new SeamHttpUserIdentities(constructorOptions) } + /** + * Creates a new SeamHttpUserIdentities authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -90,6 +102,11 @@ export class SeamHttpUserIdentities { return new SeamHttpUserIdentities(constructorOptions) } + /** + * Creates a new SeamHttpUserIdentities authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -110,6 +127,10 @@ export class SeamHttpUserIdentities { return SeamHttpUserIdentities.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpUserIdentities authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -127,6 +148,10 @@ export class SeamHttpUserIdentities { return new SeamHttpUserIdentities(constructorOptions) } + /** + * Creates a new SeamHttpUserIdentities authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -144,12 +169,21 @@ export class SeamHttpUserIdentities { return new SeamHttpUserIdentities(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -169,6 +203,9 @@ export class SeamHttpUserIdentities { await clientSessions.get() } + /** + * Client for the Seam API /user_identities/unmanaged routes. + */ get unmanaged(): SeamHttpUserIdentitiesUnmanaged { return SeamHttpUserIdentitiesUnmanaged.fromClient( this.client, diff --git a/src/lib/routes/webhooks/webhooks.ts b/src/lib/routes/webhooks/webhooks.ts index afa9c7d5..4ea201fd 100644 --- a/src/lib/routes/webhooks/webhooks.ts +++ b/src/lib/routes/webhooks/webhooks.ts @@ -34,6 +34,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /webhooks routes. + */ export class SeamHttpWebhooks { client: Client readonly defaults: Required @@ -44,6 +47,9 @@ export class SeamHttpWebhooks { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpWebhooks from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -55,6 +61,9 @@ export class SeamHttpWebhooks { return new SeamHttpWebhooks(constructorOptions) } + /** + * Creates a new SeamHttpWebhooks authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -66,6 +75,9 @@ export class SeamHttpWebhooks { return new SeamHttpWebhooks(constructorOptions) } + /** + * Creates a new SeamHttpWebhooks authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -80,6 +92,11 @@ export class SeamHttpWebhooks { return new SeamHttpWebhooks(constructorOptions) } + /** + * Creates a new SeamHttpWebhooks authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -100,6 +117,10 @@ export class SeamHttpWebhooks { return SeamHttpWebhooks.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpWebhooks authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -117,6 +138,10 @@ export class SeamHttpWebhooks { return new SeamHttpWebhooks(constructorOptions) } + /** + * Creates a new SeamHttpWebhooks authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -134,12 +159,21 @@ export class SeamHttpWebhooks { return new SeamHttpWebhooks(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { diff --git a/src/lib/routes/workspaces/workspaces.ts b/src/lib/routes/workspaces/workspaces.ts index 7f9db951..a68a8f71 100644 --- a/src/lib/routes/workspaces/workspaces.ts +++ b/src/lib/routes/workspaces/workspaces.ts @@ -36,6 +36,9 @@ import { SeamHttpClientSessions } from 'lib/routes/client-sessions/index.js' import { SeamHttpRequest } from 'lib/seam-http-request.js' import { SeamPaginator } from 'lib/seam-paginator.js' +/** + * Client for the Seam API /workspaces routes. + */ export class SeamHttpWorkspaces { client: Client readonly defaults: Required @@ -46,6 +49,9 @@ export class SeamHttpWorkspaces { this.defaults = limitToSeamHttpRequestOptions(options) } + /** + * Creates a new SeamHttpWorkspaces from an existing HTTP client. + */ static fromClient( client: SeamHttpOptionsWithClient['client'], options: Omit = {}, @@ -57,6 +63,9 @@ export class SeamHttpWorkspaces { return new SeamHttpWorkspaces(constructorOptions) } + /** + * Creates a new SeamHttpWorkspaces authenticated with an API key. + */ static fromApiKey( apiKey: SeamHttpOptionsWithApiKey['apiKey'], options: Omit = {}, @@ -68,6 +77,9 @@ export class SeamHttpWorkspaces { return new SeamHttpWorkspaces(constructorOptions) } + /** + * Creates a new SeamHttpWorkspaces authenticated with a client session token. + */ static fromClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], options: Omit< @@ -82,6 +94,11 @@ export class SeamHttpWorkspaces { return new SeamHttpWorkspaces(constructorOptions) } + /** + * Creates a new SeamHttpWorkspaces authenticated with a client session token + * for the user identified by the user identifier key. + * The client session is created with the publishable key if it does not exist. + */ static async fromPublishableKey( publishableKey: string, userIdentifierKey: string, @@ -102,6 +119,10 @@ export class SeamHttpWorkspaces { return SeamHttpWorkspaces.fromClientSessionToken(token, options) } + /** + * Creates a new SeamHttpWorkspaces authenticated with a console session token + * and scoped to a workspace. + */ static fromConsoleSessionToken( consoleSessionToken: SeamHttpOptionsWithConsoleSessionToken['consoleSessionToken'], workspaceId: SeamHttpOptionsWithConsoleSessionToken['workspaceId'], @@ -119,6 +140,10 @@ export class SeamHttpWorkspaces { return new SeamHttpWorkspaces(constructorOptions) } + /** + * Creates a new SeamHttpWorkspaces authenticated with a personal access token + * and scoped to a workspace. + */ static fromPersonalAccessToken( personalAccessToken: SeamHttpOptionsWithPersonalAccessToken['personalAccessToken'], workspaceId: SeamHttpOptionsWithPersonalAccessToken['workspaceId'], @@ -136,12 +161,21 @@ export class SeamHttpWorkspaces { return new SeamHttpWorkspaces(constructorOptions) } + /** + * Creates a new SeamPaginator to iterate over the paginated results + * of the request. + */ createPaginator( request: SeamHttpRequest, ): SeamPaginator { return new SeamPaginator(this, request) } + /** + * Updates the client session token used by this client for authentication. + * + * @throws If this client was not created with a client session token. + */ async updateClientSessionToken( clientSessionToken: SeamHttpOptionsWithClientSessionToken['clientSessionToken'], ): Promise { @@ -270,6 +304,7 @@ export type WorkspacesCreateParameters = { company_name?: string | undefined /** * Connect partner name for the new workspace. + * * @deprecated Use `company_name` instead. */ connect_partner_name?: string | null | undefined diff --git a/src/lib/seam-http-error.ts b/src/lib/seam-http-error.ts index 7e8dfe04..e16f3c2e 100644 --- a/src/lib/seam-http-error.ts +++ b/src/lib/seam-http-error.ts @@ -1,9 +1,25 @@ import type { ApiError } from './api-error-types.js' +/** + * Error thrown when the Seam API returns an error response. + */ export class SeamHttpApiError extends Error { + /** + * Error type returned by the Seam API, e.g., `invalid_input`. + */ code: string + statusCode: number + + /** + * Unique identifier of the request that failed. + * Provide this to Seam support when reporting an issue. + */ requestId: string + + /** + * Additional error-specific data returned by the Seam API, if any. + */ data?: unknown constructor(error: ApiError, statusCode: number, requestId: string) { @@ -17,12 +33,18 @@ export class SeamHttpApiError extends Error { } } +/** + * Returns true if the error is a {@link SeamHttpApiError}. + */ export const isSeamHttpApiError = ( error: unknown, ): error is SeamHttpApiError => { return error instanceof SeamHttpApiError } +/** + * Error thrown when the Seam API returns a 401 Unauthorized error response. + */ export class SeamHttpUnauthorizedError extends SeamHttpApiError { override code: 'unauthorized' override statusCode: 401 @@ -38,14 +60,21 @@ export class SeamHttpUnauthorizedError extends SeamHttpApiError { } } +/** + * Returns true if the error is a {@link SeamHttpUnauthorizedError}. + */ export const isSeamHttpUnauthorizedError = ( error: unknown, ): error is SeamHttpUnauthorizedError => { return error instanceof SeamHttpUnauthorizedError } +/** + * Error thrown when the Seam API returns an `invalid_input` error response. + */ export class SeamHttpInvalidInputError extends SeamHttpApiError { override code: 'invalid_input' + readonly #validationErrors: NonNullable constructor(error: ApiError, statusCode: number, requestId: string) { @@ -55,11 +84,20 @@ export class SeamHttpInvalidInputError extends SeamHttpApiError { this.#validationErrors = error.validation_errors ?? {} } + /** + * Returns the validation error messages for the request parameter, + * or an empty array if the parameter had no validation errors. + * + * @param paramName - Name of the request parameter. + */ getValidationErrorMessages(paramName: string): string[] { return this.#validationErrors[paramName]?._errors ?? [] } } +/** + * Returns true if the error is a {@link SeamHttpInvalidInputError}. + */ export const isSeamHttpInvalidInputError = ( error: unknown, ): error is SeamHttpInvalidInputError => { diff --git a/src/lib/seam-http-request.ts b/src/lib/seam-http-request.ts index bd2cb388..321aa871 100644 --- a/src/lib/seam-http-request.ts +++ b/src/lib/seam-http-request.ts @@ -24,6 +24,20 @@ interface SeamHttpRequestConfig { readonly actionAttempts?: ActionAttemptsClient } +/** + * A lazy request to the Seam API. + * + * Creating a SeamHttpRequest does not send anything over the network. + * The request is sent once `execute` is called, + * or when the request is awaited like a Promise, + * e.g., with `await`, `then`, `catch`, or `finally`. + * When the response contains an action attempt, + * awaiting the request also waits for the action attempt to resolve + * according to the `waitForActionAttempt` option. + * + * Before sending, the request may be inspected + * with `url`, `pathname`, `method`, `params`, and `body`. + */ export class SeamHttpRequest< const TResponse, const TResponseKey extends keyof TResponse | undefined, @@ -43,10 +57,17 @@ export class SeamHttpRequest< this.#config = config } + /** + * The key of the API response object containing the response data, + * or undefined if the endpoint returns an empty response. + */ public get responseKey(): TResponseKey { return this.#config.responseKey } + /** + * The full request URL including any serialized query parameters. + */ public get url(): URL { const { client } = this.#parent @@ -83,6 +104,12 @@ export class SeamHttpRequest< return this.#config.body } + /** + * Sends the request and returns the response data. + * If the response contains an action attempt, + * waits for the action attempt to resolve + * according to the `waitForActionAttempt` option. + */ async execute(): Promise< TResponseKey extends keyof TResponse ? TResponse[TResponseKey] : undefined > { @@ -121,6 +148,10 @@ export class SeamHttpRequest< return data } + /** + * Sends the request and returns the entire response body + * without waiting for any action attempt to resolve. + */ async fetchResponse(): Promise { const { client } = this.#parent const response = await client.request({ diff --git a/src/lib/seam-paginator.ts b/src/lib/seam-paginator.ts index 5d60b5a1..8d21d326 100644 --- a/src/lib/seam-paginator.ts +++ b/src/lib/seam-paginator.ts @@ -9,6 +9,9 @@ interface SeamPaginatorParent { declare const $brand: unique symbol +/** + * Opaque cursor identifying a page of results returned by the Seam API. + */ export type SeamPageCursor = string & { [$brand]: 'SeamPageCursor' } interface Pagination { @@ -17,6 +20,15 @@ interface Pagination { readonly nextPageUrl: string | null } +/** + * Iterates over paginated results from Seam API list endpoints. + * + * Create a SeamPaginator with the client's `createPaginator` method. + * Fetch pages manually with `firstPage` and `nextPage`, + * iterate over pages with `for await`, + * iterate over items across all pages with `flatten`, + * or collect every item into a single array with `flattenToArray`. + */ export class SeamPaginator< const TResponse, const TResponseKey extends keyof TResponse, @@ -37,12 +49,19 @@ export class SeamPaginator< this.#request = request } + /** + * Fetches the first page of results along with the pagination state. + */ async firstPage(): Promise< [EnsureReadonlyArray, Pagination] > { return await this.#fetch() } + /** + * Fetches the next page of results + * using the nextPageCursor returned with a previous page. + */ async nextPage( nextPageCursor: Pagination['nextPageCursor'], ): Promise<[EnsureReadonlyArray, Pagination]> { @@ -104,6 +123,9 @@ export class SeamPaginator< ] as const } + /** + * Fetches every page and returns all items in a single array. + */ async flattenToArray(): Promise< EnsureReadonlyArray > { @@ -117,6 +139,9 @@ export class SeamPaginator< return items as EnsureReadonlyArray } + /** + * Yields each item across all pages, fetching the next page as needed. + */ async *flatten(): AsyncGenerator< EnsureReadonlyArray > { @@ -132,6 +157,9 @@ export class SeamPaginator< } } + /** + * Yields each page of items, fetching the next page as needed. + */ async *[Symbol.asyncIterator](): AsyncGenerator< EnsureReadonlyArray > { diff --git a/src/lib/token.ts b/src/lib/token.ts index 313ce97e..26000240 100644 --- a/src/lib/token.ts +++ b/src/lib/token.ts @@ -8,14 +8,26 @@ export const clientSessionTokenPrefix = 'seam_cst' export const publishableKeyTokenPrefix = 'seam_pk' +/** + * Returns true if the token is a Seam access token. + */ export const isAccessToken = (token: string): boolean => token.startsWith(accessTokenPrefix) +/** + * Returns true if the token is a JSON Web Token (JWT). + */ export const isJwt = (token: string): boolean => token.startsWith(jwtPrefix) +/** + * Returns true if the token is any type of Seam token. + */ export const isSeamToken = (token: string): boolean => token.startsWith(tokenPrefix) +/** + * Returns true if the token is a Seam API key. + */ export const isApiKey = (token: string): boolean => !isClientSessionToken(token) && !isJwt(token) && @@ -23,13 +35,25 @@ export const isApiKey = (token: string): boolean => !isPublishableKey(token) && isSeamToken(token) +/** + * Returns true if the token is a Seam client session token. + */ export const isClientSessionToken = (token: string): boolean => token.startsWith(clientSessionTokenPrefix) +/** + * Returns true if the token is a Seam publishable key. + */ export const isPublishableKey = (token: string): boolean => token.startsWith(publishableKeyTokenPrefix) +/** + * Returns true if the token may be used as a console session token. + */ export const isConsoleSessionToken = (token: string): boolean => isJwt(token) +/** + * Returns true if the token may be used as a personal access token. + */ export const isPersonalAccessToken = (token: string): boolean => isAccessToken(token)