@slates/provider 1.0.0-rc.2 → 1.0.0-rc.21

package/src/config/config.ts

@@ -1,12 +1,14 @@
-import z from 'zod';
+import type z from 'zod';
+import type { SlateConfigDocsReference } from '../docs';
 
 export class SlateConfig<ConfigType extends {}> {
   #configSchema: z.ZodType<ConfigType>;
+  #docs: SlateConfigDocsReference[] | undefined;
   #configChanged:
     | ((params: {
         previousConfig: ConfigType | null;
         newConfig: ConfigType;
-      }) => { config: ConfigType | undefined } | void)
+      }) => { config: ConfigType | undefined } | undefined)
     | null = null;
   #getDefaultConfig: (() => ConfigType) | null = null;
 
@@ -25,11 +27,16 @@ export class SlateConfig<ConfigType extends {}> {
     return this as any as SlateConfig<NewConfigType>;
   }
 
+  docs(docs: SlateConfigDocsReference[]): SlateConfig<ConfigType> {
+    this.#docs = docs;
+    return this;
+  }
+
   onConfigChanged(
     handler: (params: {
       previousConfig: ConfigType | null;
       newConfig: ConfigType;
-    }) => { config: ConfigType | undefined } | void
+    }) => { config: ConfigType | undefined } | undefined
   ): SlateConfig<ConfigType> {
     this.#configChanged = handler;
     return this;
@@ -44,6 +51,10 @@ export class SlateConfig<ConfigType extends {}> {
     return this.#configSchema;
   }
 
+  get docsReferences() {
+    return this.#docs;
+  }
+
   get handlers() {
     return {
       configChanged: this.#configChanged,

package/src/context/context.ts

@@ -1,31 +1,111 @@
-import { SlateLogger, SlateLogMessageInput } from '../logger';
-import { SlateSpecification } from '../specification/specification';
+import { Readable } from 'node:stream';
+import {
+  createBase64Attachment,
+  createUrlAttachment,
+  type SlateAttachment
+} from '../action/attachment';
+import { type SlateLiveInvocationInfo, uploadAttachmentDirect } from '../action/directUpload';
+import type { SlateHttpTrace } from '../axios/trace';
+import type { SlateLogger, SlateLogMessageInput } from '../logger';
+import type { SlateSpecification } from '../specification/specification';
+import { PQueue } from './pQueue';
 
-export class SlateContext<ConfigType extends {}, AuthType extends {}, InputType extends {}> {
-  #config: ConfigType;
+export type { SlateLiveInvocationInfo };
+
+export type SlateAddAttachmentContent =
+  | Buffer
+  | Uint8Array
+  | ArrayBuffer
+  | ReadableStream<Uint8Array>
+  | NodeJS.ReadableStream
+  | Response;
+
+export type SlateAddAttachmentInput =
+  | {
+      type: 'url';
+      url: string | URL;
+      mimeType?: string;
+      filename?: string;
+      headers?: Record<string, string>;
+      query?: Record<string, string>;
+      refreshReference?: unknown;
+      refreshAt?: string;
+    }
+  | {
+      type: 'content';
+      content: SlateAddAttachmentContent;
+      mimeType?: string;
+      filename?: string;
+    };
+
+let isBufferLike = (value: unknown): value is Buffer | Uint8Array | ArrayBuffer =>
+  value instanceof Uint8Array || value instanceof ArrayBuffer;
+
+let toUint8Array = (value: Buffer | Uint8Array | ArrayBuffer) =>
+  value instanceof ArrayBuffer ? new Uint8Array(value) : value;
+
+let isReadableStream = (value: unknown): value is ReadableStream<Uint8Array> =>
+  typeof ReadableStream !== 'undefined' && value instanceof ReadableStream;
+
+let isNodeReadable = (value: unknown): value is NodeJS.ReadableStream =>
+  !!value &&
+  typeof value === 'object' &&
+  typeof (value as any).pipe === 'function' &&
+  typeof (value as any).on === 'function';
+
+let isResponseLike = (value: unknown): value is Response =>
+  typeof Response !== 'undefined' && value instanceof Response;
+
+let readStreamToBuffer = async (stream: ReadableStream<Uint8Array>): Promise<Buffer> => {
+  let reader = stream.getReader();
+  let chunks: Uint8Array[] = [];
+
+  while (true) {
+    let { done, value } = await reader.read();
+    if (done) break;
+    if (value) chunks.push(value);
+  }
+
+  return Buffer.concat(chunks);
+};
+
+interface NormalizedStreamInput {
+  stream: ReadableStream<Uint8Array>;
+  mimeType?: string;
+  filename?: string;
+}
+
+export class SlatePublicContext<InputType extends {}> {
   #input: InputType;
-  #auth: AuthType;
+  #httpTraces: SlateHttpTrace[] = [];
+
+  #liveInvocation: SlateLiveInvocationInfo | null;
+  #attachmentsDisabled = false;
+  #attachments: SlateAttachment[] = [];
+  #pendingUploads: Promise<void>[] = [];
+  #uploadQueue?: InstanceType<typeof PQueue>;
+
+  #getUploadQueue() {
+    if (!this.#uploadQueue) {
+      this.#uploadQueue = new PQueue({ concurrency: 10 });
+    }
+    return this.#uploadQueue;
+  }
 
   constructor(
-    config: ConfigType,
     input: InputType,
-    auth: AuthType,
-    private readonly spec: SlateSpecification<ConfigType, AuthType>,
-    private readonly logger: SlateLogger
+    private readonly spec: SlateSpecification<any, any>,
+    private readonly logger: SlateLogger,
+    liveInvocation: SlateLiveInvocationInfo | null = null
   ) {
-    this.#config = config;
     this.#input = input;
-    this.#auth = auth;
+    this.#liveInvocation = liveInvocation;
   }
 
   get specification() {
     return this.spec;
   }
 
-  get config() {
-    return Object.freeze(this.#config);
-  }
-
   get input() {
     return Object.freeze(this.#input);
   }
@@ -46,8 +126,37 @@ export class SlateContext<ConfigType extends {}, AuthType extends {}, InputType
       : never;
   }
 
-  get auth() {
-    return Object.freeze(this.#auth);
+  get registrationDetails() {
+    return Object.freeze(
+      (this.#input as any).registrationDetails
+    ) as 'registrationDetails' extends keyof InputType
+      ? InputType['registrationDetails']
+      : never;
+  }
+
+  recordHttpTrace(trace: SlateHttpTrace) {
+    this.#httpTraces.push(trace);
+  }
+
+  getHttpTraces() {
+    return this.#httpTraces.map(trace => ({
+      ...trace,
+      request: {
+        ...trace.request,
+        ...(trace.request.headers ? { headers: { ...trace.request.headers } } : {}),
+        ...(trace.request.body ? { body: { ...trace.request.body } } : {})
+      },
+      ...(trace.response
+        ? {
+            response: {
+              ...trace.response,
+              ...(trace.response.headers ? { headers: { ...trace.response.headers } } : {}),
+              ...(trace.response.body ? { body: { ...trace.response.body } } : {})
+            }
+          }
+        : {}),
+      ...(trace.error ? { error: { ...trace.error } } : {})
+    }));
   }
 
   info(message: SlateLogMessageInput) {
@@ -65,4 +174,142 @@ export class SlateContext<ConfigType extends {}, AuthType extends {}, InputType
   progress(message: SlateLogMessageInput) {
     this.logger.progress(message);
   }
+
+  async addAttachment(input: SlateAddAttachmentInput): Promise<void> {
+    if (input.type === 'url') {
+      this.#attachments.push(
+        createUrlAttachment(input.url.toString(), {
+          mimeType: input.mimeType,
+          headers: input.headers,
+          query: input.query,
+          refreshReference: input.refreshReference,
+          refreshAt: input.refreshAt
+        })
+      );
+      return;
+    }
+
+    let content = input.content;
+
+    if (isBufferLike(content)) {
+      let bytes = toUint8Array(content);
+      this.#attachments.push(
+        createBase64Attachment(Buffer.from(bytes).toString('base64'), input.mimeType)
+      );
+      return;
+    }
+
+    let normalized = await this.#normalizeStreamInput(content, {
+      mimeType: input.mimeType,
+      filename: input.filename
+    });
+    if (!normalized) return;
+
+    if (!this.#liveInvocation || this.#attachmentsDisabled) {
+      let buffer = await readStreamToBuffer(normalized.stream);
+      this.#attachments.push(
+        createBase64Attachment(buffer.toString('base64'), normalized.mimeType)
+      );
+      return;
+    }
+
+    let live = this.#liveInvocation;
+    let task = this.#getUploadQueue()
+      .add(() =>
+        uploadAttachmentDirect({
+          live,
+          mimeType: normalized.mimeType,
+          filename: normalized.filename,
+          body: normalized.stream
+        })
+      )
+      .then(attachment => {
+        this.#attachments.push(attachment);
+      })
+      .catch(err => {
+        this.#attachmentsDisabled = true;
+        this.warn({
+          message: `Attachment dropped: direct upload failed (${
+            err instanceof Error ? err.message : String(err)
+          }).`
+        });
+      });
+
+    this.#pendingUploads.push(task);
+  }
+
+  async #normalizeStreamInput(
+    input: ReadableStream<Uint8Array> | NodeJS.ReadableStream | Response,
+    opts: { mimeType?: string; filename?: string }
+  ): Promise<NormalizedStreamInput | null> {
+    if (isResponseLike(input)) {
+      if (!input.body) {
+        this.warn({ message: 'Attachment dropped: response has no body.' });
+        return null;
+      }
+      return {
+        stream: input.body,
+        mimeType: opts.mimeType ?? input.headers.get('content-type') ?? undefined,
+        filename: opts.filename
+      };
+    }
+
+    if (isReadableStream(input)) {
+      return { stream: input, mimeType: opts.mimeType, filename: opts.filename };
+    }
+
+    if (isNodeReadable(input)) {
+      return {
+        stream: Readable.toWeb(input as any) as unknown as ReadableStream<Uint8Array>,
+        mimeType: opts.mimeType,
+        filename: opts.filename
+      };
+    }
+
+    this.warn({ message: 'Attachment dropped: unsupported attachment input type.' });
+    return null;
+  }
+
+  async _finalizeAttachments(): Promise<SlateAttachment[]> {
+    await Promise.allSettled(this.#pendingUploads);
+    return this.#attachments;
+  }
+
+  _getAuthConfigForRedaction(): Record<string, unknown> | undefined {
+    return undefined;
+  }
+}
+
+export class SlateContext<
+  ConfigType extends {},
+  AuthType extends {},
+  InputType extends {}
+> extends SlatePublicContext<InputType> {
+  #config: ConfigType;
+  #auth: AuthType;
+
+  constructor(
+    config: ConfigType,
+    input: InputType,
+    auth: AuthType,
+    spec: SlateSpecification<ConfigType, AuthType>,
+    logger: SlateLogger,
+    liveInvocation: SlateLiveInvocationInfo | null = null
+  ) {
+    super(input, spec, logger, liveInvocation);
+    this.#config = config;
+    this.#auth = auth;
+  }
+
+  get config() {
+    return Object.freeze(this.#config);
+  }
+
+  get auth() {
+    return Object.freeze(this.#auth);
+  }
+
+  override _getAuthConfigForRedaction(): Record<string, unknown> | undefined {
+    return this.#auth as Record<string, unknown>;
+  }
 }

package/src/context/hook.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { SlateContext } from './context';
+import { runWithContext } from './hook';
+
+describe('slate context hook', () => {
+  it('constructs a context without requiring p-queue at construction time', () => {
+    expect(
+      () =>
+        new SlateContext(
+          {},
+          {},
+          {},
+          {} as any,
+          {
+            debug: () => {},
+            error: () => {},
+            info: () => {},
+            progress: () => {},
+            warn: () => {}
+          } as any
+        )
+    ).not.toThrow();
+  });
+
+  it('shares context storage across duplicate module instances', async () => {
+    // @ts-expect-error Vite treats the query as a distinct module instance.
+    let duplicateHook: typeof import('./hook') = await import('./hook?duplicate-instance');
+    let context = new SlateContext(
+      {},
+      {},
+      {},
+      {} as any,
+      {
+        debug: () => {},
+        error: () => {},
+        info: () => {},
+        progress: () => {},
+        warn: () => {}
+      } as any
+    );
+
+    let result = await runWithContext(context, async () => duplicateHook.getCurrentContext());
+
+    expect(result).toBe(context);
+  });
+});

package/src/context/hook.ts

@@ -1,12 +1,21 @@
 import { AsyncLocalStorage } from 'async_hooks';
-import { SlateContext } from './context';
+import type { SlateContext, SlatePublicContext } from './context';
 
-let asyncLocalStorage = new AsyncLocalStorage<SlateContext<any, any, any>>();
+let slateContextStorageKey = Symbol.for('slates.provider.context.asyncLocalStorage');
+let globalWithSlateContext = globalThis as typeof globalThis & {
+  [key: symbol]: AsyncLocalStorage<SlatePublicContext<any>> | undefined;
+};
+
+let asyncLocalStorage =
+  globalWithSlateContext[slateContextStorageKey] ??
+  new AsyncLocalStorage<SlatePublicContext<any>>();
+
+globalWithSlateContext[slateContextStorageKey] = asyncLocalStorage;
 
-export let runWithContext = <ConfigType extends {}, AuthType extends {}, InputType extends {}>(
-  context: SlateContext<ConfigType, AuthType, InputType>,
-  fn: () => Promise<void>
-) => {
+export let runWithContext = <InputType extends {}, RV>(
+  context: SlatePublicContext<InputType>,
+  fn: () => Promise<RV>
+): Promise<RV> => {
   return asyncLocalStorage.run(context, fn);
 };
 

package/src/context/index.ts

@@ -1 +1,2 @@
 export * from './context';
+export * from './hook';

package/src/context/pQueue.ts

@@ -0,0 +1,4 @@
+import PQueueImport from 'p-queue';
+import { resolveDefaultExport } from '../module/resolveDefaultExport';
+
+export let PQueue = resolveDefaultExport<typeof PQueueImport>(PQueueImport);

package/src/crypto/hmac.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { createHmacSignature, verifyHmacSignature } from './hmac';
+
+describe('createHmacSignature', () => {
+  it('creates prefixed hexadecimal HMAC signatures', () => {
+    expect(
+      createHmacSignature({
+        secret: 'secret',
+        payload: 'payload',
+        digest: 'hex',
+        prefix: 'v0='
+      })
+    ).toBe('v0=b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4');
+  });
+});
+
+describe('verifyHmacSignature', () => {
+  it('verifies prefixed hexadecimal HMAC signatures', () => {
+    expect(
+      verifyHmacSignature({
+        secret: 'secret',
+        payload: 'payload',
+        signature: 'v0=b82fcb791acec57859b989b430a826488ce2e479fdf92326bd0a2e8375a42ba4',
+        digest: 'hex',
+        prefix: 'v0='
+      })
+    ).toBe(true);
+  });
+
+  it('rejects incorrect signatures, including signatures of a different length', () => {
+    expect(
+      verifyHmacSignature({
+        secret: 'secret',
+        payload: 'payload',
+        signature: 'invalid',
+        digest: 'base64'
+      })
+    ).toBe(false);
+  });
+});

package/src/crypto/hmac.ts

@@ -0,0 +1,32 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+
+export interface CreateHmacSignatureOptions {
+  secret: string | Uint8Array;
+  payload: string | Uint8Array;
+  algorithm?: string;
+  digest: 'hex' | 'base64';
+  prefix?: string;
+}
+
+export interface VerifyHmacSignatureOptions extends CreateHmacSignatureOptions {
+  signature: string;
+}
+
+export let createHmacSignature = ({
+  secret,
+  payload,
+  algorithm = 'sha256',
+  digest,
+  prefix = ''
+}: CreateHmacSignatureOptions) =>
+  `${prefix}${createHmac(algorithm, secret).update(payload).digest(digest)}`;
+
+export let verifyHmacSignature = (options: VerifyHmacSignatureOptions) => {
+  let expected = createHmacSignature(options);
+  let expectedBytes = Buffer.from(expected);
+  let signatureBytes = Buffer.from(options.signature);
+  let lengthsMatch = signatureBytes.length === expectedBytes.length;
+  let comparableSignature = lengthsMatch ? signatureBytes : Buffer.alloc(expectedBytes.length);
+
+  return timingSafeEqual(comparableSignature, expectedBytes) && lengthsMatch;
+};

package/src/crypto/index.ts

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

package/src/docs.ts

@@ -0,0 +1,22 @@
+export interface SlateDocsReference {
+  name: string;
+  url: string;
+}
+
+export interface SlateTypedDocsReference<Type extends string> extends SlateDocsReference {
+  type?: Type;
+}
+
+export type SlateProviderDocsReference = SlateDocsReference;
+
+export type SlateConfigDocsReference = SlateTypedDocsReference<'docs.config.general'>;
+
+export type SlateActionDocsReference = SlateTypedDocsReference<'docs.action.general'>;
+
+export type SlateAuthDocsReference = SlateTypedDocsReference<
+  | 'docs.auth.oauth'
+  | 'docs.auth.oauth_scopes'
+  | 'docs.auth.token'
+  | 'docs.auth.service_account'
+  | 'docs.auth.custom'
+>;

package/src/error/api.test.ts

@@ -0,0 +1,114 @@
+import { ServiceError } from '@lowerdeck/error';
+import { describe, expect, it } from 'vitest';
+import { buildApiServiceError, collectApiErrorDetails, createApiServiceError } from './api';
+import { SlateError } from './base';
+
+describe('API service error helpers', () => {
+  it('collects unique nested API error details', () => {
+    let details: string[] = [];
+
+    collectApiErrorDetails(
+      {
+        message: 'Invalid request',
+        code: 'bad_request',
+        errors: [
+          {
+            detail: 'Missing name'
+          },
+          'Missing name'
+        ]
+      },
+      details
+    );
+
+    expect(details).toEqual(['Invalid request', 'bad_request', 'Missing name']);
+  });
+
+  it('builds provider API ServiceErrors with upstream metadata', () => {
+    let parent = new Error('Request failed');
+    (parent as any).response = {
+      status: 429,
+      statusText: 'Too Many Requests',
+      data: {
+        title: 'Rate limit',
+        details: [{ message: 'Retry later' }]
+      }
+    };
+
+    let error = buildApiServiceError(parent, {
+      providerLabel: 'Example',
+      operation: 'list widgets',
+      reason: 'example_api_error',
+      detailKeys: ['title', 'message'],
+      nestedKeys: ['details'],
+      extractUpstreamCode: () => 'RATE_LIMITED'
+    });
+
+    expect(error).toBeInstanceOf(ServiceError);
+    expect(error.data.message).toBe(
+      'Example API list widgets failed: HTTP 429 Too Many Requests: Rate limit - Retry later'
+    );
+    expect(error.data.reason).toBe('example_api_error');
+    expect(error.data.upstreamStatus).toBe(429);
+    expect(error.data.upstreamCode).toBe('RATE_LIMITED');
+  });
+
+  it('recovers the upstream status from interceptor-normalized SlateErrors', () => {
+    // Runtime axios instances reject with SlateError, not AxiosError: the
+    // response interceptor consumes error.response, so the status only
+    // survives at data.upstream.status / data.status.
+    let parent = new SlateError({
+      code: 'not_found',
+      message: 'Method not found.',
+      upstream: { status: 404 }
+    });
+
+    let error = buildApiServiceError(parent, {
+      providerLabel: 'Example',
+      operation: 'search messages',
+      reason: 'example_api_error'
+    });
+
+    expect(error.data.upstreamStatus).toBe(404);
+    expect(error.data.message).toBe(
+      'Example API search messages failed: HTTP 404: Method not found.'
+    );
+  });
+
+  it('allows provider-specific status and message extraction', () => {
+    let error = buildApiServiceError(
+      {
+        status: 503,
+        data: {
+          message: 'Unavailable'
+        }
+      },
+      {
+        providerLabel: 'Example',
+        reason: 'example_api_error',
+        extractStatus: (input, _response, helpers) =>
+          helpers.isRecord(input) && typeof input.status === 'number'
+            ? input.status
+            : undefined,
+        extractMessage: (input, helpers) => {
+          if (!helpers.isRecord(input) || !helpers.isRecord(input.data)) return undefined;
+          return typeof input.data.message === 'string' ? input.data.message : undefined;
+        }
+      }
+    );
+
+    expect(error.data.message).toBe('Example API request failed: HTTP 503: Unavailable');
+    expect(error.data.upstreamStatus).toBe(503);
+  });
+
+  it('passes through existing ServiceErrors', () => {
+    let existing = createApiServiceError('Already normalized');
+
+    expect(
+      buildApiServiceError(existing, {
+        providerLabel: 'Example',
+        reason: 'example_api_error'
+      })
+    ).toBe(existing);
+  });
+});