@vuoma/sdk 0.1.1 → 0.2.0

package/src/organization.d.ts

@@ -0,0 +1,23 @@
+import type { OrganizationReadInputs, OrganizationReadResults, OrganizationWriteInputs, OrganizationWriteResults } from './organization-contracts.generated.js'
+export type { OrganizationReadInputs, OrganizationReadResults, OrganizationReadOperationId, OrganizationWriteInputs, OrganizationWriteResults, OrganizationWriteOperationId } from './organization-contracts.generated.js'
+
+export interface OrganizationApiClientOptions {
+  apiOrigin: string
+  organizationSlug: string
+  /** Return the current exact organization API token; never a member session. */
+  getApiToken(): string | null | Promise<string | null>
+  fetch?: typeof globalThis.fetch
+  maximumResponseBytes?: number
+}
+export interface OrganizationApiClient {
+  readonly operations: {
+    readonly [Id in keyof OrganizationReadInputs]: {} extends OrganizationReadInputs[Id]
+      ? (input?: OrganizationReadInputs[Id], options?: { signal?: AbortSignal }) => Promise<OrganizationReadResults[Id]>
+      : (input: OrganizationReadInputs[Id], options?: { signal?: AbortSignal }) => Promise<OrganizationReadResults[Id]>
+  }
+  /** Explicit writes execute once; reconcile uncertain message sends before repeating. */
+  readonly writeOperations: {
+    readonly [Id in keyof OrganizationWriteInputs]: (input: OrganizationWriteInputs[Id], options?: { signal?: AbortSignal }) => Promise<OrganizationWriteResults[Id]>
+  }
+}
+export function createOrganizationApiClient(options: OrganizationApiClientOptions): OrganizationApiClient

package/src/organization.js

@@ -0,0 +1,95 @@
+import Ajv from 'ajv'
+import addFormats from 'ajv-formats'
+import { organizationReadContracts, organizationWriteContracts } from './organization-contracts.generated.js'
+import { VuomaApiError } from './index.js'
+
+const validator = new Ajv({ strict: false, allErrors: false, validateFormats: true })
+addFormats(validator)
+const contracts = new Map(organizationReadContracts.map(contract => [contract.id, {
+  ...contract, validateInput: validator.compile(contract.query_schema), validateOutput: validator.compile(contract.response_schema),
+}]))
+const writeContracts = new Map(organizationWriteContracts.map(contract => [contract.id, {
+  ...contract, validateInput: validator.compile(contract.request_schema), validateOutput: validator.compile(contract.response_schema),
+}]))
+const problem = (status, code, message) => new VuomaApiError(status, code, message)
+const unavailable = () => problem(502, 'invalid_response', 'Vuoma returned an invalid response.')
+
+/** Organization business API client. Uses the caller's exact scoped API token;
+ * never stores it or substitutes a member/account/browser credential.
+ */
+export function createOrganizationApiClient({ apiOrigin, organizationSlug, getApiToken, fetch: fetcher = globalThis.fetch, maximumResponseBytes = 2_097_152 }) {
+  let origin
+  try {
+    const url = new URL(apiOrigin)
+    if (url.username || url.password || url.search || url.hash || url.pathname !== '/' ||
+      !(url.protocol === 'https:' || url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) throw Error()
+    origin = url.origin
+  } catch { throw new TypeError('Choose a valid Vuoma API origin.') }
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(organizationSlug ?? '') || organizationSlug.length > 80) throw new TypeError('Choose a valid organization slug.')
+  if (typeof getApiToken !== 'function' || typeof fetcher !== 'function') throw new TypeError('Provide an API token adapter and fetch implementation.')
+  if (!Number.isSafeInteger(maximumResponseBytes) || maximumResponseBytes < 1024 || maximumResponseBytes > 16_777_216) throw new TypeError('Choose a bounded response size.')
+
+  async function execute(contract, path, { signal, body } = {}) {
+    const token = await getApiToken()
+    if (!/^chapi_v1_[A-Za-z0-9_-]{16}_[A-Za-z0-9_-]{43}$/u.test(token ?? '')) throw problem(401, 'api_authorization_required', 'Provide an organization API token.')
+    const response = await fetcher(`${origin}${path}`, {
+      method: contract.method, credentials: 'omit', redirect: 'manual', signal,
+      headers: { authorization: `Bearer ${token}`, accept: 'application/json', ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+      ...(body === undefined ? {} : { body }),
+    })
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => {})
+      throw problem(response.status, 'api_request_failed', response.status === 401 || response.status === 403
+        ? 'This API token or current organization permissions do not allow this operation.' : 'The API request could not be completed.')
+    }
+    const contentType = response.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase()
+    if (response.redirected || !(contentType === 'application/json' || /^application\/[a-z0-9.+-]+\+json$/u.test(contentType ?? '')) ||
+      Number(response.headers.get('content-length')) > maximumResponseBytes) {
+      await response.body?.cancel().catch(() => {})
+      throw unavailable()
+    }
+    const reader = response.body?.getReader()
+    if (!reader) throw unavailable()
+    const chunks = []
+    let bytes = 0
+    try {
+      for (;;) {
+        signal?.throwIfAborted()
+        const { done, value } = await reader.read()
+        if (done) break
+        bytes += value.byteLength
+        if (bytes > maximumResponseBytes) throw unavailable()
+        chunks.push(value)
+      }
+      const body = new Uint8Array(bytes)
+      let offset = 0
+      for (const chunk of chunks) { body.set(chunk, offset); offset += chunk.byteLength }
+      const text = new TextDecoder('utf-8', { fatal: true }).decode(body)
+      if (text.includes(token)) throw unavailable()
+      const data = JSON.parse(text)
+      if (!contract.validateOutput(data)) throw unavailable()
+      return data
+    } catch (error) {
+      await reader.cancel().catch(() => {})
+      if (signal?.aborted) throw signal.reason
+      throw unavailable()
+    } finally { reader.releaseLock() }
+  }
+  const operations = Object.fromEntries([...contracts].map(([id, contract]) => [id, async (args = {}, { signal } = {}) => {
+    if (!contract.validateInput(args)) throw new TypeError('Provide the query fields declared by this API contract.')
+    const query = new URLSearchParams(Object.entries(args).map(([name, value]) => [name, String(value)]))
+    const path = contract.path_template.replace('{organization_slug}', encodeURIComponent(organizationSlug))
+    return execute(contract, `${path}${query.size ? `?${query}` : ''}`, { signal })
+  }]))
+  // Mutation calls execute exactly once. Even idempotent preference writes do
+  // not retry internally, and message sends must be reconciled after uncertainty.
+  const writeOperations = Object.fromEntries([...writeContracts].map(([id, contract]) => [id, async (args, { signal } = {}) => {
+    if (!contract.validateInput(args)) throw new TypeError('Provide the path and body fields declared by this API contract.')
+    const body = JSON.stringify(args.body)
+    if (new TextEncoder().encode(body).byteLength > contract.maximum_body_bytes) throw new TypeError('The API request exceeds its contract byte limit.')
+    const values = { ...args.path, organization_slug: organizationSlug }
+    const path = contract.path_template.replace(/\{([a-z_]+)\}/gu, (_, name) => encodeURIComponent(values[name]))
+    return execute(contract, path, { signal, body })
+  }]))
+  return Object.freeze({ operations: Object.freeze(operations), writeOperations: Object.freeze(writeOperations) })
+}