@slates/proto 1.0.0-rc.25 → 1.0.0-rc.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slates/proto",
-  "version": "1.0.0-rc.25",
+  "version": "1.0.0-rc.27",
   "publishConfig": {
     "access": "public"
   },

package/src/handler/provider.test.ts

@@ -1,11 +1,43 @@
 import { badRequestError, ServiceError } from '@lowerdeck/error';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { createApiServiceError } from '../../../provider/src/error/api';
 import { SlateError } from '../../../provider/src/error/base';
+import type { SlateErrorResponse } from '../../../provider/src/error/types';
+import { type SlatesErrorResponse, slatesErrorResponse } from '../types';
 import {
   createSlatesProviderProtoHandler,
   SlatesProviderProtoHandlerManager
 } from './provider';
 
+// Zod looseObject adds index signatures that interfaces lack; compare declared fields only.
+type Declared<T> = T extends readonly (infer Item)[]
+  ? Declared<Item>[]
+  : T extends object
+    ? {
+        [Key in keyof T as string extends Key
+          ? never
+          : number extends Key
+            ? never
+            : Key]: Declared<T[Key]>;
+      }
+    : T;
+
+describe('slate error response shape', () => {
+  it('keeps the provider SlateErrorResponse and the proto schema in sync', () => {
+    type Provider = Declared<SlateErrorResponse>;
+    type Proto = Declared<SlatesErrorResponse>;
+
+    expectTypeOf<Provider>().toExtend<Proto>();
+    expectTypeOf<keyof Provider>().toEqualTypeOf<keyof Proto>();
+    expectTypeOf<keyof NonNullable<Provider['upstream']>>().toEqualTypeOf<
+      keyof NonNullable<Proto['upstream']>
+    >();
+    expectTypeOf<keyof NonNullable<Provider['provider']>>().toEqualTypeOf<
+      keyof NonNullable<Proto['provider']>
+    >();
+  });
+});
+
 describe('SlatesProviderProtoHandlerManager', () => {
   it('serializes SlateError instances directly into JSON-RPC errors', async () => {
     let manager = await createSlatesProviderProtoHandler(async manager => {
@@ -46,6 +78,7 @@ describe('SlatesProviderProtoHandlerManager', () => {
           status: 429,
           code: 'rate_limited'
         },
+        upstreamCode: 'rate_limited',
         baggage: {
           scope: 'issues'
         }
@@ -118,4 +151,140 @@ describe('SlatesProviderProtoHandlerManager', () => {
       }
     });
   });
+
+  let throwFromIdentify = async (error: unknown) => {
+    let manager = await createSlatesProviderProtoHandler(async manager => {
+      manager.onRequest('slates/provider.identify', async () => {
+        throw error;
+      });
+    }).run();
+
+    let response = await SlatesProviderProtoHandlerManager.handleInput(manager, {
+      jsonrpc: '2.0',
+      id: 'req_upstream',
+      method: 'slates/provider.identify',
+      params: {}
+    });
+
+    return (response as { error: Record<string, unknown> }).error;
+  };
+
+  it('surfaces the upstream code of API service errors as a top-level field', async () => {
+    let error = await throwFromIdentify(
+      createApiServiceError('Stripe API request failed: 402 - Card declined', {
+        upstreamStatus: 402,
+        upstreamCode: 'card_declined'
+      })
+    );
+
+    expect(error).toEqual({
+      code: 'request.bad',
+      kind: 'request',
+      message: 'Stripe API request failed: 402 - Card declined',
+      retryable: false,
+      status: 400,
+      upstreamCode: 'card_declined',
+      baggage: {
+        serviceError: {
+          code: 'bad_request',
+          status: 400
+        },
+        serviceErrorData: {
+          upstreamStatus: 402,
+          upstreamCode: 'card_declined'
+        }
+      }
+    });
+    expect(slatesErrorResponse.parse(error).upstreamCode).toBe('card_declined');
+  });
+
+  it('omits upstreamCode when the service error has no string upstream code', async () => {
+    for (let upstreamCode of [undefined, '']) {
+      let error = await throwFromIdentify(
+        createApiServiceError('Upstream failed', { upstreamStatus: 500, upstreamCode })
+      );
+      expect(error).not.toHaveProperty('upstreamCode');
+    }
+
+    let numeric = new ServiceError(badRequestError({ message: 'Upstream failed' }));
+    numeric.data.upstreamCode = 42;
+    expect(await throwFromIdentify(numeric)).not.toHaveProperty('upstreamCode');
+  });
+
+  it('drops upstreamCode values that are not code-shaped', async () => {
+    for (let upstreamCode of ['x'.repeat(129), 'has space', '`x`', 'a\nb', '<script>']) {
+      expect(
+        await throwFromIdentify(
+          createApiServiceError('Upstream failed', { upstreamStatus: 400, upstreamCode })
+        )
+      ).not.toHaveProperty('upstreamCode');
+
+      let payload = await throwFromIdentify({
+        code: 'upstream.error',
+        kind: 'upstream',
+        message: 'Upstream failed',
+        upstreamCode,
+        upstream: { code: upstreamCode }
+      });
+      expect(payload).not.toHaveProperty('upstreamCode');
+    }
+
+    expect(
+      await throwFromIdentify({
+        code: 'upstream.error',
+        kind: 'upstream',
+        message: 'Upstream failed',
+        upstreamCode: 'not a code',
+        upstream: { code: 'AADSTS700016' }
+      })
+    ).toMatchObject({ upstreamCode: 'AADSTS700016' });
+  });
+
+  it('keeps upstreamCode in service error baggage for older hubs', async () => {
+    let error = await throwFromIdentify(
+      createApiServiceError('Upstream failed', { upstreamCode: 'invalid_grant' })
+    );
+
+    expect(error).toMatchObject({
+      upstreamCode: 'invalid_grant',
+      baggage: { serviceErrorData: { upstreamCode: 'invalid_grant' } }
+    });
+  });
+
+  it('derives upstreamCode from upstream.code for slate error payloads that predate it', async () => {
+    let error = await throwFromIdentify({
+      code: 'upstream.error',
+      kind: 'upstream',
+      message: 'Upstream failed',
+      upstream: { status: 502, code: 'BAD_GATEWAY' }
+    });
+
+    expect(error).toMatchObject({ code: 'upstream.error', upstreamCode: 'BAD_GATEWAY' });
+  });
+
+  it('keeps an explicit upstreamCode on slate errors', async () => {
+    let error = await throwFromIdentify(
+      new SlateError({
+        code: 'upstream.error',
+        message: 'Upstream failed',
+        upstream: { code: 'nested' },
+        upstreamCode: 'explicit'
+      })
+    );
+
+    expect(error).toMatchObject({ upstream: { code: 'nested' }, upstreamCode: 'explicit' });
+  });
+
+  it('carries the upstream code when a service error is converted to a SlateError', async () => {
+    let error = await throwFromIdentify(
+      SlateError.fromServiceError(
+        createApiServiceError('Rate limited', {
+          upstreamStatus: 429,
+          upstreamCode: 'RATE_LIMITED'
+        })
+      )
+    );
+
+    expect(error).toMatchObject({ code: 'request.bad', upstreamCode: 'RATE_LIMITED' });
+  });
 });

package/src/handler/provider.ts

@@ -12,6 +12,7 @@ import {
   slatesNotificationsByMethod,
   slatesRequestsByMethod
 } from '../messages';
+import type { SlatesErrorResponse } from '../types';
 
 export class SlatesProviderProtoHandlerManager {
   #implMap = new Map<
@@ -163,9 +164,9 @@ export let createSlatesProviderProtoHandler = (
 let toSlateErrorResponse = (
   error: unknown,
   defaults: Partial<{ code: string; message: string }> = {}
-) => {
+): SlatesErrorResponse => {
   let slateError = getSlateErrorResponse(error);
-  if (slateError) return slateError;
+  if (slateError) return withUpstreamCode(slateError);
 
   let serviceError = getServiceErrorData(error);
   if (serviceError) {
@@ -199,9 +200,7 @@ let isRecord = (value: unknown): value is Record<string, unknown> =>
 let isStructuredValue = (value: unknown): value is Record<string, unknown> | Function =>
   (typeof value === 'object' || typeof value === 'function') && value !== null;
 
-let isSlateErrorPayload = (
-  value: unknown
-): value is { code: string; message: string; kind?: string; [key: string]: unknown } =>
+let isSlateErrorPayload = (value: unknown): value is SlatesErrorResponse =>
   isRecord(value) &&
   typeof value.code === 'string' &&
   typeof value.message === 'string' &&
@@ -273,6 +272,20 @@ let getServiceErrorData = (error: unknown) => {
   return null;
 };
 
+let UPSTREAM_CODE_PATTERN = /^[\w.:-]{1,128}$/;
+
+// upstreamCode is copied from untrusted upstream responses to the top level of the
+// error, so anything not code-shaped is dropped.
+let normalizeUpstreamCode = (value: unknown): string | undefined =>
+  typeof value === 'string' && UPSTREAM_CODE_PATTERN.test(value) ? value : undefined;
+
+let withUpstreamCode = (response: SlatesErrorResponse): SlatesErrorResponse => {
+  let { upstreamCode: rawUpstreamCode, ...rest } = response;
+  let upstreamCode =
+    normalizeUpstreamCode(rawUpstreamCode) ?? normalizeUpstreamCode(response.upstream?.code);
+  return upstreamCode ? { ...rest, upstreamCode } : rest;
+};
+
 let mapKind = (code: string) => {
   if (code.startsWith('declaration.')) return 'declaration';
   if (code.startsWith('input.')) return 'validation';
@@ -345,6 +358,7 @@ let mapServiceErrorToSlateErrorResponse = (
   defaults: Partial<{ code: string; message: string }> = {}
 ) => {
   let code = defaults.code ?? mapServiceErrorCode(error.code, error.status);
+  let upstreamCode = normalizeUpstreamCode(error.upstreamCode);
   let extraEntries = Object.entries(error).filter(
     ([key]) =>
       ![
@@ -367,6 +381,7 @@ let mapServiceErrorToSlateErrorResponse = (
     retryable: mapRetryable(code),
     status: error.status,
     ...(mapIssues(error.errors) ? { issues: mapIssues(error.errors) } : {}),
+    ...(upstreamCode ? { upstreamCode } : {}),
     baggage: {
       serviceError: {
         code: error.code,

package/src/messages/auth.ts

@@ -208,6 +208,72 @@ export type SlatesMessageAuthAuthorizationCallbackHandleResponse = z.infer<
   typeof slatesMessageAuthAuthorizationCallbackHandleResponse
 >;
 
+/**
+ * Get Admin Authorization Url
+ */
+export let slatesMessageAuthAdminAuthorizationUrlGetRequest = z.object({
+  jsonrpc: z.literal('2.0'),
+  method: z.literal('slates/auth.admin_authorization_url.get'),
+  id: z.string(),
+  params: slatesMessageAuthAuthorizationUrlGetRequest.shape.params
+});
+
+export type SlatesMessageAuthAdminAuthorizationUrlGetRequest = z.infer<
+  typeof slatesMessageAuthAdminAuthorizationUrlGetRequest
+>;
+
+export let slatesMessageAuthAdminAuthorizationUrlGetResponse = z.object({
+  jsonrpc: z.literal('2.0'),
+  id: z.string(),
+  result: withRequestTraces({
+    authorizationUrl: z.string(),
+    input: z.record(z.string(), z.any()).optional(),
+    callbackState: z.record(z.string(), z.any()).optional()
+  })
+});
+
+export type SlatesMessageAuthAdminAuthorizationUrlGetResponse = z.infer<
+  typeof slatesMessageAuthAdminAuthorizationUrlGetResponse
+>;
+
+/**
+ * Handle Admin Callback
+ */
+export let slatesMessageAuthAdminCallbackHandleRequest = z.object({
+  jsonrpc: z.literal('2.0'),
+  method: z.literal('slates/auth.admin_callback.handle'),
+  id: z.string(),
+  params: z.object({
+    authenticationMethodId: z.string(),
+
+    code: z.string().optional(),
+    state: z.string(),
+    redirectUri: z.string(),
+    input: z.record(z.string(), z.any()),
+    clientId: z.string(),
+    clientSecret: z.string(),
+    scopes: z.array(z.string()),
+    callbackParams: z.record(z.string(), z.string()).optional(),
+    callbackState: z.record(z.string(), z.any()).optional()
+  })
+});
+
+export type SlatesMessageAuthAdminCallbackHandleRequest = z.infer<
+  typeof slatesMessageAuthAdminCallbackHandleRequest
+>;
+
+export let slatesMessageAuthAdminCallbackHandleResponse = z.object({
+  jsonrpc: z.literal('2.0'),
+  id: z.string(),
+  result: withRequestTraces({
+    instructions: z.string().optional()
+  })
+});
+
+export type SlatesMessageAuthAdminCallbackHandleResponse = z.infer<
+  typeof slatesMessageAuthAdminCallbackHandleResponse
+>;
+
 /**
  * Handle Token Refresh
  */
@@ -314,6 +380,8 @@ export type SlatesAuthRequests =
   | SlatesMessageAuthDefaultInputGetRequest
   | SlatesMessageAuthAuthorizationUrlGetRequest
   | SlatesMessageAuthAuthorizationCallbackHandleRequest
+  | SlatesMessageAuthAdminAuthorizationUrlGetRequest
+  | SlatesMessageAuthAdminCallbackHandleRequest
   | SlatesMessageAuthTokenRefreshHandleRequest
   | SlatesMessageAuthProfileGetRequest
   | SlatesMessageAuthOutputGetRequest;
@@ -325,6 +393,8 @@ export type SlatesAuthResponses =
   | SlatesMessageAuthDefaultInputGetResponse
   | SlatesMessageAuthAuthorizationUrlGetResponse
   | SlatesMessageAuthAuthorizationCallbackHandleResponse
+  | SlatesMessageAuthAdminAuthorizationUrlGetResponse
+  | SlatesMessageAuthAdminCallbackHandleResponse
   | SlatesMessageAuthTokenRefreshHandleResponse
   | SlatesMessageAuthProfileGetResponse
   | SlatesMessageAuthOutputGetResponse;
@@ -339,6 +409,8 @@ export let slatesAuthResponsesByMethod = {
   'slates/auth.authorization_url.get': slatesMessageAuthAuthorizationUrlGetResponse,
   'slates/auth.authorization_callback.handle':
     slatesMessageAuthAuthorizationCallbackHandleResponse,
+  'slates/auth.admin_authorization_url.get': slatesMessageAuthAdminAuthorizationUrlGetResponse,
+  'slates/auth.admin_callback.handle': slatesMessageAuthAdminCallbackHandleResponse,
   'slates/auth.token_refresh.handle': slatesMessageAuthTokenRefreshHandleResponse,
   'slates/auth.profile.get': slatesMessageAuthProfileGetResponse,
   'slates/auth.output.get': slatesMessageAuthOutputGetResponse
@@ -352,6 +424,8 @@ export let slatesAuthRequestsByMethod = {
   'slates/auth.authorization_url.get': slatesMessageAuthAuthorizationUrlGetRequest,
   'slates/auth.authorization_callback.handle':
     slatesMessageAuthAuthorizationCallbackHandleRequest,
+  'slates/auth.admin_authorization_url.get': slatesMessageAuthAdminAuthorizationUrlGetRequest,
+  'slates/auth.admin_callback.handle': slatesMessageAuthAdminCallbackHandleRequest,
   'slates/auth.token_refresh.handle': slatesMessageAuthTokenRefreshHandleRequest,
   'slates/auth.profile.get': slatesMessageAuthProfileGetRequest,
   'slates/auth.output.get': slatesMessageAuthOutputGetRequest

package/src/types/authMethod.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { slatesAuthenticationMethod } from './authMethod';
+
+let authMethod = {
+  id: 'oauth',
+  name: 'OAuth',
+  type: 'auth.oauth',
+  inputSchema: {},
+  outputSchema: {},
+  docs: []
+};
+
+describe('slatesAuthenticationMethod', () => {
+  it('parses the adminSetup capability with and without the required flag', () => {
+    for (let adminSetup of [
+      { enabled: true },
+      { enabled: true, required: false },
+      { enabled: true, required: true }
+    ]) {
+      let parsed = slatesAuthenticationMethod.parse({
+        ...authMethod,
+        capabilities: { adminSetup }
+      });
+      expect(parsed.capabilities.adminSetup).toEqual(adminSetup);
+    }
+  });
+
+  it('rejects a non-boolean required flag', () => {
+    expect(
+      slatesAuthenticationMethod.safeParse({
+        ...authMethod,
+        capabilities: { adminSetup: { enabled: true, required: 'yes' } }
+      }).success
+    ).toBe(false);
+  });
+});

package/src/types/authMethod.ts

@@ -32,7 +32,8 @@ export let slatesAuthenticationMethod = z.object({
     getDefaultInput: z.object({ enabled: z.boolean() }).optional(),
     handleChangedInput: z.object({ enabled: z.boolean() }).optional(),
     handleTokenRefresh: z.object({ enabled: z.boolean() }).optional(),
-    getProfile: z.object({ enabled: z.boolean() }).optional()
+    getProfile: z.object({ enabled: z.boolean() }).optional(),
+    adminSetup: z.object({ enabled: z.boolean(), required: z.boolean().optional() }).optional()
   }),
 
   docs: z.array(

package/src/types/error.ts

@@ -0,0 +1,47 @@
+import z from 'zod';
+import { slatesRequestTrace } from '../messages/tracing';
+
+export let slatesErrorResponse = z.looseObject({
+  code: z.string(),
+  kind: z.string(),
+  message: z.string(),
+  retryable: z.boolean().optional(),
+  status: z.number().optional(),
+
+  issues: z
+    .array(
+      z.looseObject({
+        path: z.array(z.string()).optional(),
+        code: z.string().optional(),
+        message: z.string()
+      })
+    )
+    .optional(),
+
+  provider: z
+    .looseObject({
+      key: z.string().optional(),
+      service: z.string().optional(),
+      operation: z.string().optional()
+    })
+    .optional(),
+
+  upstream: z
+    .looseObject({
+      status: z.number().optional(),
+      code: z.string().optional(),
+      type: z.string().optional(),
+      requestId: z.string().optional(),
+      method: z.string().optional(),
+      url: z.string().optional()
+    })
+    .optional(),
+
+  // The upstream API's own error code, next to the normalized protocol `code`.
+  upstreamCode: z.string().optional(),
+
+  baggage: z.record(z.string(), z.unknown()).optional(),
+  requestTraces: z.array(slatesRequestTrace).optional()
+});
+
+export type SlatesErrorResponse = z.infer<typeof slatesErrorResponse>;

package/src/types/index.ts

@@ -1,6 +1,7 @@
 export * from './action';
 export * from './adapter';
 export * from './authMethod';
+export * from './error';
 export * from './participant';
 export * from './toolCategory';
 export * from './triggerGroup';