@slates/provider 1.0.0-rc.33 → 1.0.0-rc.35

package/src/action/triggerGroup.ts

@@ -3,11 +3,14 @@ import type { SlateContext } from '../context';
 import { SlateDeclarationError } from '../error';
 import type { SlateSpecification } from '../specification/specification';
 import type { SlateWebhookHttpResponseInit } from './action';
+import type { SlateOptionListPage } from './optionList';
 
 export let SlateDefaultPollingIntervalSeconds = 60 * 10;
 
 export type SlateTriggerRoutingMatcher = Record<string, any>;
 
+export type SlateTriggerGroupSelection = Record<string, any>;
+
 export type SlateWebhookTargetOwnership = 'single_user' | 'multi_user';
 
 export interface SlateWebhookTarget {
@@ -24,8 +27,86 @@ export type SlateTriggerGroupRoutingMatchersHandler<
   AuthType extends {}
 > = (context: SlateContext<ConfigType, AuthType, {}>) => Promise<SlateTriggerRoutingMatcher[]>;
 
+/** Lists the values an account can pick for one selection field. `selection` holds what is entered so far and may be incomplete. */
+export type SlateTriggerGroupSelectionOptionsHandler<
+  ConfigType extends {},
+  AuthType extends {}
+> = (
+  context: SlateContext<
+    ConfigType,
+    AuthType,
+    { query: string | null; pageToken: any | null; selection: SlateTriggerGroupSelection }
+  >
+) => Promise<SlateOptionListPage>;
+
+/** An option list exported by another integration, run with that integration's connection for the same account. */
+export interface SlateLinkedOptionList {
+  /** Registry name of the integration, as `<scope>/<name>`. */
+  slate: string;
+  optionList: string;
+  params?: Record<string, any>;
+}
+
+export interface SlateTriggerGroupSelectionOptionsSources<
+  ConfigType extends {},
+  AuthType extends {}
+> {
+  list?: SlateTriggerGroupSelectionOptionsHandler<ConfigType, AuthType>;
+  linked?: SlateLinkedOptionList;
+}
+
+let LINKED_SLATE_PATTERN = /^[^/\s]+\/[^/\s]+$/;
+
+let checkSelectionOptions = <ConfigType extends {}, AuthType extends {}>(
+  field: string,
+  sources: SlateTriggerGroupSelectionOptionsSources<ConfigType, AuthType>,
+  shape: Record<string, unknown>
+): SlateTriggerGroupSelectionOptionsSources<ConfigType, AuthType> => {
+  if (!Object.hasOwn(shape, field)) {
+    throw new SlateDeclarationError(
+      `Selection field "${field}" is not a top-level property of the selection schema`
+    );
+  }
+  if (typeof sources !== 'object' || sources === null) {
+    throw new SlateDeclarationError(
+      `Selection field "${field}" must be declared as { list, linked }`
+    );
+  }
+
+  let { list, linked } = sources;
+  if (!list && !linked) {
+    throw new SlateDeclarationError(
+      `Selection field "${field}" needs its own options list, a linked option list, or both`
+    );
+  }
+  if (list !== undefined && typeof list !== 'function') {
+    throw new SlateDeclarationError(`Selection field "${field}" list must be a function`);
+  }
+  if (linked) {
+    if (typeof linked.slate !== 'string' || !LINKED_SLATE_PATTERN.test(linked.slate)) {
+      throw new SlateDeclarationError(
+        `Selection field "${field}" links to slate "${linked.slate}", which must be written as <scope>/<name>`
+      );
+    }
+    if (typeof linked.optionList !== 'string' || !linked.optionList.trim()) {
+      throw new SlateDeclarationError(
+        `Selection field "${field}" must name the option list it links to`
+      );
+    }
+  }
+
+  return {
+    ...(list ? { list } : {}),
+    ...(linked ? { linked } : {})
+  };
+};
+
 export type SlateTriggerGroupPollHandler<ConfigType extends {}, AuthType extends {}> = (
-  context: SlateContext<ConfigType, AuthType, { state: any | null }>
+  context: SlateContext<
+    ConfigType,
+    AuthType,
+    { state: any | null; selection?: SlateTriggerGroupSelection }
+  >
 ) => Promise<{
   events: { payload: any; idempotencyKey?: string }[];
   updatedState?: any;
@@ -65,7 +146,11 @@ export type SlateTriggerGroupGatewayReceiveHandler<
 }>;
 
 export type SlateWebhookTargetListHandler<ConfigType extends {}, AuthType extends {}> = (
-  context: SlateContext<ConfigType, AuthType, { pageToken: any | null }>
+  context: SlateContext<
+    ConfigType,
+    AuthType,
+    { pageToken: any | null; selection?: SlateTriggerGroupSelection }
+  >
 ) => Promise<{
   targets: SlateWebhookTarget[];
   nextPageToken: any | null;
@@ -81,11 +166,54 @@ export type SlateWebhookRegisterHandler<ConfigType extends {}, AuthType extends
       webhookTargetIdentifier: string;
       webhookTargetPayload: any;
       webhookUrl: string;
+      operationId?: string;
+      selection?: SlateTriggerGroupSelection;
+      deliveryConfig?: unknown;
     }
   >
-) => Promise<{
+) => Promise<SlateWebhookRegistrationResult>;
+
+export interface SlateWebhookRegistrationResult {
   webhookRegistrationIdentifier: string;
   webhookRegistrationPayload: any;
+  expiresAt?: string | null;
+  renewAfter?: string | null;
+  /** Identities of this registration on a delivery channel shared with other registrations. */
+  routingKeys?: string[];
+}
+
+export type SlateWebhookRenewHandler<ConfigType extends {}, AuthType extends {}> = (
+  context: SlateContext<
+    ConfigType,
+    AuthType,
+    {
+      webhookRegistrationIdentifier: string;
+      webhookRegistrationPayload: any;
+      webhookUrl: string;
+      webhookTargetIdentifier: string;
+      webhookTargetPayload: any;
+      operationId: string;
+      selection?: SlateTriggerGroupSelection;
+      deliveryConfig?: unknown;
+    }
+  >
+) => Promise<SlateWebhookRegistrationResult>;
+
+export type SlateWebhookExpandHandler<ConfigType extends {}, AuthType extends {}> = (
+  context: SlateContext<
+    ConfigType,
+    AuthType,
+    {
+      payload: unknown | null;
+      state: any | null;
+      selection?: SlateTriggerGroupSelection;
+      deliveryId: string;
+      webhookRegistrationPayload: any;
+    }
+  >
+) => Promise<{
+  events: { payload: any; idempotencyKey?: string }[];
+  updatedState?: any;
 }>;
 
 export type SlateWebhookUnregisterHandler<ConfigType extends {}, AuthType extends {}> = (
@@ -146,6 +274,18 @@ export interface SlateWebhookSkipped {
   reason: string;
 }
 
+/**
+ * Routing keys name the registrations a request addresses; an empty list acknowledges it
+ * without handing it to any. A rejection answers the sender with its status.
+ */
+export type SlateWebhookDeliveryAuthentication =
+  | { routingKeys: string[]; rejected?: undefined }
+  | { rejected: { status: number }; routingKeys?: undefined };
+
+export type SlateWebhookDeliveryAuthenticateHandler = (
+  context: SlateContext<{}, {}, { request: Request; deliveryConfig: unknown }>
+) => Promise<SlateWebhookDeliveryAuthentication>;
+
 export interface SlateTriggerGroupPollingParameters<
   ConfigType extends {},
   AuthType extends {}
@@ -168,6 +308,7 @@ export interface SlateTriggerGroupWebhookAutoRegistrationParameters<
 > {
   webhookTargetList: SlateWebhookTargetListHandler<ConfigType, AuthType>;
   webhookRegister: SlateWebhookRegisterHandler<ConfigType, AuthType>;
+  webhookRenew?: SlateWebhookRenewHandler<ConfigType, AuthType>;
   webhookUnregister: SlateWebhookUnregisterHandler<ConfigType, AuthType>;
 }
 
@@ -181,13 +322,28 @@ export interface SlateTriggerGroupWebhookManualRegistrationParameters<
   finish?: SlateWebhookManualFinishHandler<UserConfigSchema, FullConfigSchema>;
 }
 
+/** A delivery setup a person completes once for an automatically registered group. */
+export type SlateTriggerGroupWebhookDeliveryConfigParameters<
+  UserConfigSchema extends z.ZodType<any> = z.ZodType<any>,
+  FullConfigSchema extends z.ZodType<any> = z.ZodType<any>
+> = SlateTriggerGroupWebhookManualRegistrationParameters<
+  UserConfigSchema,
+  FullConfigSchema
+> & {
+  finish: SlateWebhookManualFinishHandler<UserConfigSchema, FullConfigSchema>;
+  authenticate: SlateWebhookDeliveryAuthenticateHandler;
+};
+
 export interface SlateTriggerGroupWebhookParameters<
   ConfigType extends {},
   AuthType extends {}
 > {
   autoRegistration?: SlateTriggerGroupWebhookAutoRegistrationParameters<ConfigType, AuthType>;
   manualRegistration?: SlateTriggerGroupWebhookManualRegistrationParameters<any, any>;
+  deliveryConfig?: SlateTriggerGroupWebhookDeliveryConfigParameters<any, any>;
   process: SlateWebhookProcessHandler;
+  expandWebhook?: SlateWebhookExpandHandler<ConfigType, AuthType>;
+  reconcileIntervalSeconds?: number;
 }
 
 export interface SlateTriggerGroupCreateParameters<
@@ -198,6 +354,7 @@ export interface SlateTriggerGroupCreateParameters<
   description?: string;
   metadata?: Record<string, any>;
   eventSchema?: z.ZodType<InputType>;
+  selectionSchema?: z.ZodType<SlateTriggerGroupSelection>;
 }
 
 export interface SlateTriggerGroupParameters<
@@ -210,6 +367,10 @@ export interface SlateTriggerGroupParameters<
   webhook?: SlateTriggerGroupWebhookParameters<ConfigType, AuthType>;
   gateway?: SlateTriggerGroupGatewayParameters<ConfigType, AuthType>;
   routingMatchers: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType>;
+  selectionOptions?: Record<
+    string,
+    SlateTriggerGroupSelectionOptionsSources<ConfigType, AuthType>
+  >;
 }
 
 export class SlateTriggerGroup<
@@ -261,6 +422,10 @@ export class SlateTriggerGroup<
     return this._params.source;
   }
 
+  get selectionSchema() {
+    return this._params.selectionSchema;
+  }
+
   get polling() {
     return this._params.polling;
   }
@@ -276,6 +441,10 @@ export class SlateTriggerGroup<
   get routingMatchers() {
     return this._params.routingMatchers;
   }
+
+  get selectionOptions() {
+    return this._params.selectionOptions ?? {};
+  }
 }
 
 export class SlateTriggerGroupBuilder<
@@ -289,6 +458,10 @@ export class SlateTriggerGroupBuilder<
   #gateway: SlateTriggerGroupGatewayParameters<ConfigType, AuthType> | null = null;
   #routingMatchers: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType> | null =
     null;
+  #selectionOptions: Record<
+    string,
+    SlateTriggerGroupSelectionOptionsSources<ConfigType, AuthType>
+  > = {};
 
   constructor(
     private readonly spec: SlateSpecification<ConfigType, AuthType>,
@@ -327,7 +500,13 @@ export class SlateTriggerGroupBuilder<
       UserConfigSchema,
       FullConfigSchema
     >;
+    deliveryConfig?: SlateTriggerGroupWebhookDeliveryConfigParameters<
+      UserConfigSchema,
+      FullConfigSchema
+    >;
     process: SlateWebhookProcessHandler;
+    expandWebhook?: SlateWebhookExpandHandler<ConfigType, AuthType>;
+    reconcileIntervalSeconds?: number;
   }): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType> {
     if (this.#source) {
       throw new SlateDeclarationError('Trigger group invocation is already defined');
@@ -339,11 +518,46 @@ export class SlateTriggerGroupBuilder<
       );
     }
 
+    if (props.deliveryConfig !== undefined) {
+      if (!props.autoRegistration) {
+        throw new SlateDeclarationError(
+          'A webhook delivery config requires automatic webhook registration'
+        );
+      }
+      if (!props.deliveryConfig.finish) {
+        throw new SlateDeclarationError('A webhook delivery config requires a finish handler');
+      }
+      if (!props.deliveryConfig.authenticate) {
+        throw new SlateDeclarationError(
+          'A webhook delivery config requires an authenticate handler'
+        );
+      }
+    }
+
+    if (props.reconcileIntervalSeconds !== undefined) {
+      if (
+        !Number.isSafeInteger(props.reconcileIntervalSeconds) ||
+        props.reconcileIntervalSeconds < 900
+      ) {
+        throw new SlateDeclarationError(
+          'Webhook reconciliation interval must be an integer of at least 900 seconds'
+        );
+      }
+      if (!props.expandWebhook) {
+        throw new SlateDeclarationError(
+          'Webhook reconciliation requires an expandWebhook handler'
+        );
+      }
+    }
+
     this.#source = 'webhook';
     this.#webhook = {
       autoRegistration: props.autoRegistration,
       manualRegistration: props.manualRegistration,
-      process: props.process
+      deliveryConfig: props.deliveryConfig,
+      process: props.process,
+      expandWebhook: props.expandWebhook,
+      reconcileIntervalSeconds: props.reconcileIntervalSeconds
     };
 
     return this;
@@ -370,6 +584,34 @@ export class SlateTriggerGroupBuilder<
     return this;
   }
 
+  /**
+   * Lets the dashboard offer a list for these selection fields instead of a typed-in value.
+   * Each field must be a top-level property of the selection schema, which must be a zod object.
+   * For an array property the listed options are values for its items.
+   */
+  selectionOptions(
+    declarations: Record<
+      string,
+      SlateTriggerGroupSelectionOptionsSources<ConfigType, AuthType>
+    >
+  ): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType> {
+    let schema = this.params.selectionSchema;
+    if (!schema) {
+      throw new SlateDeclarationError('Selection options require a selection schema');
+    }
+    if (schema._zod?.def?.type !== 'object') {
+      throw new SlateDeclarationError(
+        'Selection options require the selection schema to be a zod object'
+      );
+    }
+
+    let shape = (schema as z.ZodObject<any>).shape;
+    for (let [field, sources] of Object.entries(declarations)) {
+      this.#selectionOptions[field] = checkSelectionOptions(field, sources, shape);
+    }
+    return this;
+  }
+
   build(): SlateTriggerGroup<ConfigType, AuthType, InputType> {
     if (!this.#source) {
       throw new SlateDeclarationError(
@@ -386,7 +628,8 @@ export class SlateTriggerGroupBuilder<
       polling: this.#polling ?? undefined,
       webhook: this.#webhook ?? undefined,
       gateway: this.#gateway ?? undefined,
-      routingMatchers: this.#routingMatchers
+      routingMatchers: this.#routingMatchers,
+      selectionOptions: this.#selectionOptions
     });
   }
 }

package/src/crypto/hmac.test.ts

@@ -1,5 +1,21 @@
 import { describe, expect, it } from 'vitest';
-import { createHmacSignature, verifyHmacSignature } from './hmac';
+import { createHmacSignature, timingSafeStringEqual, verifyHmacSignature } from './hmac';
+
+describe('timingSafeStringEqual', () => {
+  it('matches only the identical string', () => {
+    expect(timingSafeStringEqual('secret', 'secret')).toBe(true);
+    expect(timingSafeStringEqual('secret', 'secreT')).toBe(false);
+    expect(timingSafeStringEqual('secret', 'secret-longer')).toBe(false);
+    expect(timingSafeStringEqual('secret', '')).toBe(false);
+  });
+
+  it('rejects a missing value and never matches an empty expectation', () => {
+    expect(timingSafeStringEqual('secret', null)).toBe(false);
+    expect(timingSafeStringEqual('', undefined)).toBe(false);
+    expect(timingSafeStringEqual('', null)).toBe(false);
+    expect(timingSafeStringEqual('', '')).toBe(false);
+  });
+});
 
 describe('createHmacSignature', () => {
   it('creates prefixed hexadecimal HMAC signatures', () => {

package/src/crypto/hmac.ts

@@ -21,12 +21,17 @@ export let createHmacSignature = ({
 }: CreateHmacSignatureOptions) =>
   `${prefix}${createHmac(algorithm, secret).update(payload).digest(digest)}`;
 
-export let verifyHmacSignature = (options: VerifyHmacSignatureOptions) => {
-  let expected = createHmacSignature(options);
+/** Constant-time secret comparison; an empty expected secret matches nothing. */
+export let timingSafeStringEqual = (expected: string, received: string | null | undefined) => {
   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);
+  let receivedBytes = Buffer.from(received ?? '');
+  let lengthsMatch = receivedBytes.length === expectedBytes.length;
+  let comparable = lengthsMatch ? receivedBytes : Buffer.alloc(expectedBytes.length);
 
-  return timingSafeEqual(comparableSignature, expectedBytes) && lengthsMatch;
+  return (
+    timingSafeEqual(comparable, expectedBytes) && lengthsMatch && expectedBytes.length > 0
+  );
 };
+
+export let verifyHmacSignature = (options: VerifyHmacSignatureOptions) =>
+  timingSafeStringEqual(createHmacSignature(options), options.signature);

package/src/dedup/index.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it, vi } from 'vitest';
+import { pruneSeenEntries, seenEntryKey, seenEntrySchema } from './index';
+
+describe('seen entries', () => {
+  it('derives a short stable key', () => {
+    let key = seenEntryKey('["account","event",1]');
+    expect(key).toMatch(/^[A-Za-z0-9_-]{16}$/);
+    expect(seenEntryKey('["account","event",1]')).toBe(key);
+    expect(seenEntryKey('["account","event",2]')).not.toBe(key);
+    expect(seenEntrySchema.safeParse({ key, at: 1 }).success).toBe(true);
+    expect(seenEntrySchema.safeParse({ key, at: Number.NaN }).success).toBe(false);
+  });
+
+  it('drops entries before the cutoff unless retained, newest first', () => {
+    expect(
+      pruneSeenEntries(
+        [
+          { key: 'old', at: 1 },
+          { key: 'kept', at: 1, retain: true },
+          { key: 'b', at: 5 },
+          { key: 'a', at: 5 },
+          { key: 'new', at: 9 }
+        ],
+        { cutoff: 5, maxEntries: 10 }
+      )
+    ).toEqual([
+      { key: 'new', at: 9 },
+      { key: 'a', at: 5 },
+      { key: 'b', at: 5 },
+      { key: 'kept', at: 1 }
+    ]);
+  });
+
+  it('keeps the newest entries and reports the overflow', () => {
+    let onOverflow = vi.fn();
+    expect(
+      pruneSeenEntries(
+        [1, 2, 3, 4].map(at => ({ key: `k${at}`, at })),
+        { cutoff: 0, maxEntries: 2, onOverflow }
+      )
+    ).toEqual([
+      { key: 'k4', at: 4 },
+      { key: 'k3', at: 3 }
+    ]);
+    expect(onOverflow).toHaveBeenCalledWith(2);
+  });
+});

package/src/dedup/index.ts

@@ -0,0 +1,25 @@
+import { createHash } from 'crypto';
+import { z } from 'zod';
+
+/** An event a poller already reported, saved so an overlapping read can skip it. */
+export let seenEntrySchema = z.object({ key: z.string().min(1), at: z.number().finite() });
+export type SeenEntry = z.infer<typeof seenEntrySchema>;
+
+/** A short stable key for an idempotency key, so remembered events cost little state. */
+export let seenEntryKey = (idempotencyKey: string) =>
+  createHash('sha256').update(idempotencyKey).digest('base64url').slice(0, 16);
+
+/** Keeps entries at or after `cutoff` (or `retain`), newest first, at most `maxEntries`. */
+export let pruneSeenEntries = (
+  entries: Iterable<SeenEntry & { retain?: boolean }>,
+  options: { cutoff: number; maxEntries: number; onOverflow?: (dropped: number) => void }
+): SeenEntry[] => {
+  let kept: SeenEntry[] = [];
+  for (let { key, at, retain } of entries) {
+    if (retain || at >= options.cutoff) kept.push({ key, at });
+  }
+  kept.sort((a, b) => b.at - a.at || (a.key < b.key ? -1 : 1));
+  if (kept.length <= options.maxEntries) return kept;
+  options.onOverflow?.(kept.length - options.maxEntries);
+  return kept.slice(0, options.maxEntries);
+};

package/src/error/api.test.ts

@@ -7,6 +7,7 @@ import {
   createApiServiceError,
   decodeApiErrorBody,
   getApiErrorResponseWithBody,
+  getUpstreamErrorStatus,
   looksLikeHtmlErrorBody,
   pushBoundedApiErrorDetail,
   readApiErrorText,
@@ -97,6 +98,27 @@ describe('API service error helpers', () => {
     );
   });
 
+  it('reads the upstream status from client errors and normalized ServiceErrors', () => {
+    expect(getUpstreamErrorStatus(axiosFailure(404, {}))).toBe(404);
+    expect(
+      getUpstreamErrorStatus(
+        new SlateError({ code: 'gone', message: 'Gone.', upstream: { status: 410 } })
+      )
+    ).toBe(410);
+    expect(
+      getUpstreamErrorStatus(createApiServiceError('Conflict', { upstreamStatus: 409 }))
+    ).toBe(409);
+    expect(
+      getUpstreamErrorStatus(createApiServiceError('Limited', { upstreamStatus: '429' }))
+    ).toBe(429);
+    expect(getUpstreamErrorStatus(createApiServiceError('No status'))).toBeUndefined();
+    expect(
+      getUpstreamErrorStatus(createApiServiceError('Bad', { upstreamStatus: 'ECONNRESET' }))
+    ).toBeUndefined();
+    expect(getUpstreamErrorStatus(new Error('ETIMEDOUT'))).toBeUndefined();
+    expect(getUpstreamErrorStatus(null)).toBeUndefined();
+  });
+
   it('allows provider-specific status and message extraction', () => {
     let error = buildApiServiceError(
       {

package/src/error/api.ts

@@ -149,6 +149,14 @@ export let getApiErrorResponse = (error: unknown): ApiErrorResponse | undefined
 export let getApiErrorStatus = (error: unknown): ApiErrorStatus | undefined =>
   getApiErrorResponse(error)?.status;
 
+/** Upstream HTTP status of an HTTP client error or a ServiceError with `upstreamStatus`. */
+export let getUpstreamErrorStatus = (error: unknown): number | undefined => {
+  let value =
+    error instanceof ServiceError ? error.data.upstreamStatus : getApiErrorStatus(error);
+  let status = Number(value);
+  return Number.isInteger(status) && status >= 100 && status <= 599 ? status : undefined;
+};
+
 // Like getApiErrorResponse, but also recovers the upstream response body from
 // interceptor-normalized SlateErrors. createAxios stores the body (sanitized by
 // sanitizeForBaggage) at SlateError.data.baggage.response, so provider-specific

package/src/error/index.ts

@@ -2,5 +2,6 @@ export * from './api';
 export * from './axios';
 export * from './base';
 export * from './declaration';
+export * from './parse';
 export * from './service';
 export * from './types';

package/src/error/parse.test.ts

@@ -0,0 +1,29 @@
+import { ServiceError } from '@lowerdeck/error';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { parseWithServiceError } from './parse';
+
+describe('parseWithServiceError', () => {
+  let schema = z.object({ id: z.string().min(1), tags: z.array(z.string()).default([]) });
+
+  it('returns the parsed output, including defaults', () => {
+    expect(parseWithServiceError(schema, { id: 'a' }, 'Invalid value.')).toEqual({
+      id: 'a',
+      tags: []
+    });
+  });
+
+  it('throws a ServiceError with the message and reason', () => {
+    let error: unknown;
+    try {
+      parseWithServiceError(schema, { id: '' }, 'The saved value is invalid.', {
+        reason: 'saved_value_invalid'
+      });
+    } catch (caught) {
+      error = caught;
+    }
+    expect(error).toBeInstanceOf(ServiceError);
+    expect((error as ServiceError<any>).data.message).toBe('The saved value is invalid.');
+    expect((error as ServiceError<any>).data.reason).toBe('saved_value_invalid');
+  });
+});

package/src/error/parse.ts

@@ -0,0 +1,14 @@
+import type { z } from 'zod';
+import { createApiServiceError } from './api';
+
+/** Parses a saved or received value, throwing a user-facing `ServiceError` on mismatch. */
+export let parseWithServiceError = <T extends z.ZodType>(
+  schema: T,
+  value: unknown,
+  message: string,
+  options: { reason?: string } = {}
+): z.output<T> => {
+  let result = schema.safeParse(value);
+  if (!result.success) throw createApiServiceError(message, options);
+  return result.data;
+};

package/src/index.ts

@@ -7,10 +7,12 @@ export * from './axios';
 export * from './config';
 export * from './context';
 export * from './crypto';
+export * from './dedup';
 export * from './docs';
 export * from './error';
 export * from './file';
 export * from './logger';
 export * from './object';
+export * from './pagination';
 export * from './specification';
 export * from './webhook';

package/src/pagination/index.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { assertNewPageToken, rememberPageToken } from './index';
+
+describe('page token guards', () => {
+  it('remembers each token once', () => {
+    let seen = new Set<string>();
+    expect(rememberPageToken(seen, 'a')).toBe(true);
+    expect(rememberPageToken(seen, 'b')).toBe(true);
+    expect(rememberPageToken(seen, 'a')).toBe(false);
+  });
+
+  it('throws the caller error only for a repeated token', () => {
+    let seen = new Set<string>(['start']);
+    let repeated = () => new Error('repeated');
+    expect(() => assertNewPageToken(seen, undefined, repeated)).not.toThrow();
+    expect(() => assertNewPageToken(seen, '', repeated)).not.toThrow();
+    expect(() => assertNewPageToken(seen, 'next', repeated)).not.toThrow();
+    expect(() => assertNewPageToken(seen, 'next', repeated)).toThrow('repeated');
+    expect(() => assertNewPageToken(seen, 'start', repeated)).toThrow('repeated');
+  });
+});

package/src/pagination/index.ts

@@ -0,0 +1,15 @@
+/** Records a page token in `seen`; `false` means it repeated and following it would loop. */
+export let rememberPageToken = (seen: Set<string>, token: string) => {
+  if (seen.has(token)) return false;
+  seen.add(token);
+  return true;
+};
+
+/** Throws `repeated()` when a listing returns a page token it already returned. */
+export let assertNewPageToken = (
+  seen: Set<string>,
+  token: string | null | undefined,
+  repeated: () => unknown
+) => {
+  if (token && !rememberPageToken(seen, token)) throw repeated();
+};