@slates/provider 1.0.0-rc.30 → 1.0.0-rc.32

package/dist/index.cjs

@@ -1309,6 +1309,8 @@ var sanitizeForBaggage = (value, options = {}) => {
     return BAGGAGE_UNSERIALIZABLE_VALUE;
   }
 };
+var UPSTREAM_CODE_PATTERN = /^[\w.:-]{1,128}$/;
+var normalizeUpstreamCode = (value) => typeof value === "string" && UPSTREAM_CODE_PATTERN.test(value) ? value : void 0;
 var normalizeSlateErrorInput = (input) => {
   let code = input.code || DEFAULT_CODE;
   return {
@@ -1323,6 +1325,7 @@ var normalizeSlateErrorInput = (input) => {
       ...input.upstream,
       status: input.upstream?.status ?? input.status
     }),
+    upstreamCode: normalizeUpstreamCode(input.upstreamCode) ?? normalizeUpstreamCode(input.upstream?.code),
     baggage: cleanRecord(input.baggage),
     requestTraces: input.requestTraces
   };
@@ -1785,6 +1788,7 @@ var mapServiceErrorToSlateErrorInput = (error, defaults = {}) => {
     issues: defaults.issues ?? normalizeServiceErrorIssues(data.errors),
     provider: defaults.provider,
     upstream: defaults.upstream,
+    upstreamCode: normalizeUpstreamCode(defaults.upstreamCode) ?? normalizeUpstreamCode(data.upstreamCode),
     baggage: cleanRecord({
       ...defaults.baggage ?? {},
       ...getServiceErrorBaggage(data)

package/dist/index.d.cts

@@ -147,6 +147,35 @@ type SlateActionDocsReference = SlateTypedDocsReference<'docs.action.general'>;
 type SlateAuthDocsReference = SlateTypedDocsReference<'docs.auth.oauth' | 'docs.auth.oauth_scopes' | 'docs.auth.token' | 'docs.auth.service_account' | 'docs.auth.custom'>;
 
 type SlateAuthCallbackConfig = Record<string, any>;
+type SlateOauthAuthorizationUrlContext<InputType> = {
+    redirectUri: string;
+    state: string;
+    input: InputType;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+};
+type SlateOauthAuthorizationUrlResult<InputType> = {
+    url: string;
+    input?: InputType;
+    callbackState?: Record<string, any>;
+};
+type SlateOauthCallbackContext<InputType> = {
+    code: string;
+    state: string;
+    redirectUri: string;
+    input: InputType;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+    callbackParams?: Record<string, string>;
+    callbackState: Record<string, any>;
+    config?: SlateAuthCallbackConfig;
+};
+type SlateOauthAdminCallbackContext<InputType> = Omit<SlateOauthCallbackContext<InputType>, 'code'> & {
+    code?: string;
+};
 type SlateAuthWithOauth<InputType extends {}, OutputType extends {
     token: string;
     refreshToken?: string;
@@ -162,6 +191,13 @@ type SlateAuthWithOauth<InputType extends {}, OutputType extends {
     }[];
     adapters?: string[];
     syncTokensAcrossConnections?: boolean;
+    adminSetup?: {
+        required?: boolean;
+        getAuthorizationUrl?: (ctx: SlateOauthAuthorizationUrlContext<InputType>) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
+        handleCallback?: (ctx: SlateOauthAdminCallbackContext<InputType>) => Promise<{
+            instructions?: string;
+        }>;
+    };
     docs?: SlateAuthDocsReference[];
     inputSchema?: z.ZodType<InputType>;
     onInputChanged?: (params: {
@@ -171,31 +207,8 @@ type SlateAuthWithOauth<InputType extends {}, OutputType extends {
         input?: InputType;
     } | undefined>;
     getDefaultInput?: () => Promise<InputType>;
-    getAuthorizationUrl: (ctx: {
-        redirectUri: string;
-        state: string;
-        input: InputType;
-        clientId: string;
-        clientSecret: string;
-        scopes: string[];
-        config?: SlateAuthCallbackConfig;
-    }) => Promise<{
-        url: string;
-        input?: InputType;
-        callbackState?: Record<string, any>;
-    }>;
-    handleCallback: (ctx: {
-        code: string;
-        state: string;
-        redirectUri: string;
-        input: InputType;
-        clientId: string;
-        clientSecret: string;
-        scopes: string[];
-        callbackParams?: Record<string, string>;
-        callbackState: Record<string, any>;
-        config?: SlateAuthCallbackConfig;
-    }) => Promise<{
+    getAuthorizationUrl: (ctx: SlateOauthAuthorizationUrlContext<InputType>) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
+    handleCallback: (ctx: SlateOauthCallbackContext<InputType>) => Promise<{
         output: OutputType;
         input?: InputType;
         scopes?: string[];
@@ -1064,6 +1077,7 @@ interface SlateErrorResponse {
     issues?: SlateErrorIssue[];
     provider?: SlateErrorProviderInfo;
     upstream?: SlateErrorUpstreamInfo;
+    upstreamCode?: string;
     baggage?: Record<string, unknown>;
     requestTraces?: SlateHttpTrace[];
 }

package/dist/index.d.ts

@@ -147,6 +147,35 @@ type SlateActionDocsReference = SlateTypedDocsReference<'docs.action.general'>;
 type SlateAuthDocsReference = SlateTypedDocsReference<'docs.auth.oauth' | 'docs.auth.oauth_scopes' | 'docs.auth.token' | 'docs.auth.service_account' | 'docs.auth.custom'>;
 
 type SlateAuthCallbackConfig = Record<string, any>;
+type SlateOauthAuthorizationUrlContext<InputType> = {
+    redirectUri: string;
+    state: string;
+    input: InputType;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+    config?: SlateAuthCallbackConfig;
+};
+type SlateOauthAuthorizationUrlResult<InputType> = {
+    url: string;
+    input?: InputType;
+    callbackState?: Record<string, any>;
+};
+type SlateOauthCallbackContext<InputType> = {
+    code: string;
+    state: string;
+    redirectUri: string;
+    input: InputType;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+    callbackParams?: Record<string, string>;
+    callbackState: Record<string, any>;
+    config?: SlateAuthCallbackConfig;
+};
+type SlateOauthAdminCallbackContext<InputType> = Omit<SlateOauthCallbackContext<InputType>, 'code'> & {
+    code?: string;
+};
 type SlateAuthWithOauth<InputType extends {}, OutputType extends {
     token: string;
     refreshToken?: string;
@@ -162,6 +191,13 @@ type SlateAuthWithOauth<InputType extends {}, OutputType extends {
     }[];
     adapters?: string[];
     syncTokensAcrossConnections?: boolean;
+    adminSetup?: {
+        required?: boolean;
+        getAuthorizationUrl?: (ctx: SlateOauthAuthorizationUrlContext<InputType>) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
+        handleCallback?: (ctx: SlateOauthAdminCallbackContext<InputType>) => Promise<{
+            instructions?: string;
+        }>;
+    };
     docs?: SlateAuthDocsReference[];
     inputSchema?: z.ZodType<InputType>;
     onInputChanged?: (params: {
@@ -171,31 +207,8 @@ type SlateAuthWithOauth<InputType extends {}, OutputType extends {
         input?: InputType;
     } | undefined>;
     getDefaultInput?: () => Promise<InputType>;
-    getAuthorizationUrl: (ctx: {
-        redirectUri: string;
-        state: string;
-        input: InputType;
-        clientId: string;
-        clientSecret: string;
-        scopes: string[];
-        config?: SlateAuthCallbackConfig;
-    }) => Promise<{
-        url: string;
-        input?: InputType;
-        callbackState?: Record<string, any>;
-    }>;
-    handleCallback: (ctx: {
-        code: string;
-        state: string;
-        redirectUri: string;
-        input: InputType;
-        clientId: string;
-        clientSecret: string;
-        scopes: string[];
-        callbackParams?: Record<string, string>;
-        callbackState: Record<string, any>;
-        config?: SlateAuthCallbackConfig;
-    }) => Promise<{
+    getAuthorizationUrl: (ctx: SlateOauthAuthorizationUrlContext<InputType>) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
+    handleCallback: (ctx: SlateOauthCallbackContext<InputType>) => Promise<{
         output: OutputType;
         input?: InputType;
         scopes?: string[];
@@ -1064,6 +1077,7 @@ interface SlateErrorResponse {
     issues?: SlateErrorIssue[];
     provider?: SlateErrorProviderInfo;
     upstream?: SlateErrorUpstreamInfo;
+    upstreamCode?: string;
     baggage?: Record<string, unknown>;
     requestTraces?: SlateHttpTrace[];
 }

package/dist/index.module.js

@@ -1184,6 +1184,8 @@ var sanitizeForBaggage = (value, options = {}) => {
     return BAGGAGE_UNSERIALIZABLE_VALUE;
   }
 };
+var UPSTREAM_CODE_PATTERN = /^[\w.:-]{1,128}$/;
+var normalizeUpstreamCode = (value) => typeof value === "string" && UPSTREAM_CODE_PATTERN.test(value) ? value : void 0;
 var normalizeSlateErrorInput = (input) => {
   let code = input.code || DEFAULT_CODE;
   return {
@@ -1198,6 +1200,7 @@ var normalizeSlateErrorInput = (input) => {
       ...input.upstream,
       status: input.upstream?.status ?? input.status
     }),
+    upstreamCode: normalizeUpstreamCode(input.upstreamCode) ?? normalizeUpstreamCode(input.upstream?.code),
     baggage: cleanRecord(input.baggage),
     requestTraces: input.requestTraces
   };
@@ -1660,6 +1663,7 @@ var mapServiceErrorToSlateErrorInput = (error, defaults = {}) => {
     issues: defaults.issues ?? normalizeServiceErrorIssues(data.errors),
     provider: defaults.provider,
     upstream: defaults.upstream,
+    upstreamCode: normalizeUpstreamCode(defaults.upstreamCode) ?? normalizeUpstreamCode(data.upstreamCode),
     baggage: cleanRecord({
       ...defaults.baggage ?? {},
       ...getServiceErrorBaggage(data)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slates/provider",
-  "version": "1.0.0-rc.30",
+  "version": "1.0.0-rc.32",
   "publishConfig": {
     "access": "public"
   },

package/src/auth/types.ts

@@ -3,6 +3,42 @@ import type { SlateAuthDocsReference } from '../docs';
 
 type SlateAuthCallbackConfig = Record<string, any>;
 
+type SlateOauthAuthorizationUrlContext<InputType> = {
+  redirectUri: string;
+  state: string;
+  input: InputType;
+  clientId: string;
+  clientSecret: string;
+  scopes: string[];
+  config?: SlateAuthCallbackConfig;
+};
+
+type SlateOauthAuthorizationUrlResult<InputType> = {
+  url: string;
+  input?: InputType;
+  callbackState?: Record<string, any>;
+};
+
+type SlateOauthCallbackContext<InputType> = {
+  code: string;
+  state: string;
+  redirectUri: string;
+  input: InputType;
+  clientId: string;
+  clientSecret: string;
+  scopes: string[];
+  callbackParams?: Record<string, string>;
+  callbackState: Record<string, any>;
+  config?: SlateAuthCallbackConfig;
+};
+
+type SlateOauthAdminCallbackContext<InputType> = Omit<
+  SlateOauthCallbackContext<InputType>,
+  'code'
+> & {
+  code?: string;
+};
+
 export type SlateAuthWithOauth<
   InputType extends {},
   OutputType extends {
@@ -28,6 +64,21 @@ export type SlateAuthWithOauth<
   // connection of one installation, so a refresh must update all of them.
   syncTokensAcrossConnections?: boolean;
 
+  // Missing hooks fall back to the regular flow (callback output discarded).
+  // Returned instructions are markdown shown to the admin. `required` means users
+  // can't connect until an admin has completed setup; otherwise it is optional.
+  adminSetup?: {
+    required?: boolean;
+
+    getAuthorizationUrl?: (
+      ctx: SlateOauthAuthorizationUrlContext<InputType>
+    ) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
+
+    handleCallback?: (
+      ctx: SlateOauthAdminCallbackContext<InputType>
+    ) => Promise<{ instructions?: string }>;
+  };
+
   docs?: SlateAuthDocsReference[];
 
   inputSchema?: z.ZodType<InputType>;
@@ -39,32 +90,11 @@ export type SlateAuthWithOauth<
 
   getDefaultInput?: () => Promise<InputType>;
 
-  getAuthorizationUrl: (ctx: {
-    redirectUri: string;
-    state: string;
-    input: InputType;
-    clientId: string;
-    clientSecret: string;
-    scopes: string[];
-    config?: SlateAuthCallbackConfig;
-  }) => Promise<{
-    url: string;
-    input?: InputType;
-    callbackState?: Record<string, any>;
-  }>;
+  getAuthorizationUrl: (
+    ctx: SlateOauthAuthorizationUrlContext<InputType>
+  ) => Promise<SlateOauthAuthorizationUrlResult<InputType>>;
 
-  handleCallback: (ctx: {
-    code: string;
-    state: string;
-    redirectUri: string;
-    input: InputType;
-    clientId: string;
-    clientSecret: string;
-    scopes: string[];
-    callbackParams?: Record<string, string>;
-    callbackState: Record<string, any>;
-    config?: SlateAuthCallbackConfig;
-  }) => Promise<{
+  handleCallback: (ctx: SlateOauthCallbackContext<InputType>) => Promise<{
     output: OutputType;
     input?: InputType;
     scopes?: string[];

package/src/error/base.test.ts

@@ -17,6 +17,7 @@ import {
 } from '@lowerdeck/error';
 import { AxiosError, type AxiosResponse, type InternalAxiosRequestConfig } from 'axios';
 import { describe, expect, it } from 'vitest';
+import { createApiServiceError } from './api';
 import { SlateError } from './base';
 
 let createConfig = (overrides: Partial<InternalAxiosRequestConfig> = {}) =>
@@ -175,4 +176,80 @@ describe('SlateError', () => {
       });
     }
   });
+
+  it('exposes the upstream API error code as a top-level upstreamCode', () => {
+    expect(
+      new SlateError({ code: 'upstream.error', message: 'x', upstream: { code: 'E42' } }).data
+        .upstreamCode
+    ).toBe('E42');
+    expect(
+      new SlateError({
+        code: 'upstream.error',
+        message: 'x',
+        upstream: { code: 'nested' },
+        upstreamCode: 'explicit'
+      }).data.upstreamCode
+    ).toBe('explicit');
+    expect(
+      SlateError.fromServiceError(
+        createApiServiceError('x', { upstreamCode: 'card_declined' })
+      ).data.upstreamCode
+    ).toBe('card_declined');
+    expect(new SlateError({ code: 'upstream.error', message: 'x' }).data.upstreamCode).toBe(
+      undefined
+    );
+  });
+
+  it('accepts only code-shaped upstreamCode values', () => {
+    for (let code of [
+      'AADSTS700016',
+      'invalid_grant',
+      'RATE_LIMITED',
+      'request.bad',
+      'a:b-c'
+    ]) {
+      expect(
+        new SlateError({ code: 'upstream.error', message: 'x', upstreamCode: code }).data
+          .upstreamCode
+      ).toBe(code);
+    }
+
+    for (let code of ['', 'x'.repeat(129), 'has space', 'token=abc&x', 'line\nbreak', '`x`']) {
+      expect(
+        new SlateError({ code: 'upstream.error', message: 'x', upstreamCode: code }).data
+          .upstreamCode
+      ).toBe(undefined);
+      expect(
+        SlateError.fromServiceError(createApiServiceError('x', { upstreamCode: code })).data
+          .upstreamCode
+      ).toBe(undefined);
+    }
+
+    expect(
+      SlateError.fromServiceError(
+        createApiServiceError('x', { upstreamCode: { nested: true } as unknown as string })
+      ).data.upstreamCode
+    ).toBe(undefined);
+    expect(
+      new SlateError({ code: 'upstream.error', message: 'x', upstreamCode: 'x'.repeat(128) })
+        .data.upstreamCode
+    ).toBe('x'.repeat(128));
+    expect(
+      new SlateError({
+        code: 'upstream.error',
+        message: 'x',
+        upstreamCode: 'bad value',
+        upstream: { code: 'fallback_code' }
+      }).data.upstreamCode
+    ).toBe('fallback_code');
+  });
+
+  it('also keeps upstreamCode in service error baggage for older hubs', () => {
+    let error = SlateError.fromServiceError(
+      createApiServiceError('x', { upstreamCode: 'card_declined' })
+    );
+    expect(error.data.baggage?.serviceErrorData).toMatchObject({
+      upstreamCode: 'card_declined'
+    });
+  });
 });

package/src/error/service.ts

@@ -7,6 +7,7 @@ import {
   isRecord,
   normalizeKind,
   normalizeRetryable,
+  normalizeUpstreamCode,
   sanitizeForBaggage
 } from './utils';
 
@@ -162,6 +163,8 @@ export let mapServiceErrorToSlateErrorInput = (
     issues: defaults.issues ?? normalizeServiceErrorIssues(data.errors),
     provider: defaults.provider,
     upstream: defaults.upstream,
+    upstreamCode:
+      normalizeUpstreamCode(defaults.upstreamCode) ?? normalizeUpstreamCode(data.upstreamCode),
     baggage: cleanRecord({
       ...(defaults.baggage ?? {}),
       ...getServiceErrorBaggage(data)

package/src/error/types.ts

@@ -45,6 +45,8 @@ export interface SlateErrorResponse {
   issues?: SlateErrorIssue[];
   provider?: SlateErrorProviderInfo;
   upstream?: SlateErrorUpstreamInfo;
+  // The upstream API's own error code, next to the normalized protocol `code`.
+  upstreamCode?: string;
   baggage?: Record<string, unknown>;
   requestTraces?: SlateHttpTrace[];
 }

package/src/error/utils.ts

@@ -389,6 +389,13 @@ export let sanitizeForBaggage = (
   }
 };
 
+let UPSTREAM_CODE_PATTERN = /^[\w.:-]{1,128}$/;
+
+// upstreamCode is copied from untrusted upstream responses to the top level of the
+// error, outside the baggage sanitizer, so anything not code-shaped is dropped.
+export let normalizeUpstreamCode = (value: unknown): string | undefined =>
+  typeof value === 'string' && UPSTREAM_CODE_PATTERN.test(value) ? value : undefined;
+
 export let normalizeSlateErrorInput = (input: SlateErrorInput): SlateErrorResponse => {
   let code = input.code || DEFAULT_CODE;
   return {
@@ -405,6 +412,8 @@ export let normalizeSlateErrorInput = (input: SlateErrorInput): SlateErrorRespon
       ...input.upstream,
       status: input.upstream?.status ?? input.status
     }) as SlateErrorUpstreamInfo | undefined,
+    upstreamCode:
+      normalizeUpstreamCode(input.upstreamCode) ?? normalizeUpstreamCode(input.upstream?.code),
     baggage: cleanRecord(input.baggage),
     requestTraces: input.requestTraces
   };