@slates/proto 1.0.0-rc.6 → 1.0.0-rc.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slates/proto",
-  "version": "1.0.0-rc.6",
+  "version": "1.0.0-rc.7",
   "publishConfig": {
     "access": "public"
   },
@@ -11,7 +11,7 @@
     "package.json"
   ],
   "author": "Tobias Herber",
-  "license": "Apache 2",
+  "license": "FSL 1.1",
   "type": "module",
   "source": "src/index.ts",
   "exports": {
@@ -23,23 +23,24 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.module.js",
   "types": "dist/index.d.ts",
-  "unpkg": "./dist/index.umd.js",
+  "unpkg": "./dist/index.module.js",
   "scripts": {
     "test": "vitest run --passWithNoTests",
     "lint": "prettier src/**/*.ts --check",
-    "build": "microbundle"
+    "build": "tsup --config ../../tsup.packages.config.ts",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@lowerdeck/emitter": "^1.0.4",
-    "@lowerdeck/error": "^1.0.8",
+    "@lowerdeck/error": "^1.1.0",
     "@toon-format/toon": "^2.1.0",
     "axios": "^1.13.2",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "microbundle": "^0.15.1",
-    "@slates/tsconfig": "^1.0.0",
+    "@slates/tsconfig": "1.0.0-rc.1",
     "typescript": "5.8.2",
     "vitest": "^3.1.2"
   }
-}
+}

package/src/handler/provider.test.ts

@@ -0,0 +1,118 @@
+import { ServiceError, badRequestError } from '@lowerdeck/error';
+import { describe, expect, it } from 'vitest';
+import { SlateError } from '../../../provider/src/error/base';
+import { createSlatesProviderProtoHandler, SlatesProviderProtoHandlerManager } from './provider';
+
+describe('SlatesProviderProtoHandlerManager', () => {
+  it('serializes SlateError instances directly into JSON-RPC errors', async () => {
+    let manager = await createSlatesProviderProtoHandler(async manager => {
+      manager.onRequest('slates/provider.identify', async () => {
+        throw new SlateError({
+          code: 'upstream.rate_limited',
+          kind: 'upstream',
+          message: 'GitHub rate limit exceeded',
+          retryable: true,
+          upstream: {
+            status: 429,
+            code: 'rate_limited'
+          },
+          baggage: {
+            scope: 'issues'
+          }
+        });
+      });
+    }).run();
+
+    let response = await SlatesProviderProtoHandlerManager.handleInput(manager, {
+      jsonrpc: '2.0',
+      id: 'req_1',
+      method: 'slates/provider.identify',
+      params: {}
+    });
+
+    expect(response).toEqual({
+      jsonrpc: '2.0',
+      id: 'req_1',
+      error: {
+        code: 'upstream.rate_limited',
+        kind: 'upstream',
+        message: 'GitHub rate limit exceeded',
+        retryable: true,
+        status: 429,
+        upstream: {
+          status: 429,
+          code: 'rate_limited'
+        },
+        baggage: {
+          scope: 'issues'
+        }
+      }
+    });
+  });
+
+  it('maps ServiceError instances to SlateError protocol responses', async () => {
+    let manager = await createSlatesProviderProtoHandler(async manager => {
+      manager.onRequest('slates/provider.identify', async () => {
+        throw new ServiceError(
+          badRequestError({
+            message: 'Invalid provider state'
+          })
+        );
+      });
+    }).run();
+
+    let response = await SlatesProviderProtoHandlerManager.handleInput(manager, {
+      jsonrpc: '2.0',
+      id: 'req_2',
+      method: 'slates/provider.identify',
+      params: {}
+    });
+
+    expect(response).toEqual({
+      jsonrpc: '2.0',
+      id: 'req_2',
+      error: {
+        code: 'request.bad',
+        kind: 'request',
+        message: 'Invalid provider state',
+        retryable: false,
+        status: 400,
+        baggage: {
+          serviceError: {
+            code: 'bad_request',
+            status: 400
+          }
+        }
+      }
+    });
+  });
+
+  it('returns slate errors for protocol validation failures', async () => {
+    let manager = await createSlatesProviderProtoHandler(async () => {}).run();
+
+    let response = await SlatesProviderProtoHandlerManager.handleInput(manager, {
+      jsonrpc: '1.0',
+      id: 'req_3',
+      method: 'slates/provider.identify',
+      params: {}
+    } as any);
+
+    expect(response).toEqual({
+      jsonrpc: '2.0',
+      id: 'req_3',
+      error: {
+        code: 'request.bad',
+        kind: 'request',
+        message: 'Invalid jsonrpc version',
+        retryable: false,
+        status: 400,
+        baggage: {
+          serviceError: {
+            code: 'bad_request',
+            status: 400
+          }
+        }
+      }
+    });
+  });
+});

package/src/handler/provider.ts

@@ -1,17 +1,16 @@
 import {
   badRequestError,
-  internalServerError,
   isServiceError,
   notFoundError,
   validationError
 } from '@lowerdeck/error';
-import z from 'zod';
+import type z from 'zod';
 import {
-  SlatesNotifications,
+  type SlatesNotifications,
+  type SlatesRequests,
+  type SlatesResponsesByMethod,
   slatesNotificationsByMethod,
-  SlatesRequests,
-  slatesRequestsByMethod,
-  SlatesResponsesByMethod
+  slatesRequestsByMethod
 } from '../messages';
 
 export class SlatesProviderProtoHandlerManager {
@@ -64,7 +63,7 @@ export class SlatesProviderProtoHandlerManager {
         return {
           jsonrpc: '2.0' as const,
           id: (input as any).id,
-          error: badRequestError({ message: 'Invalid input' }).toResponse()
+          error: toSlateErrorResponse(badRequestError({ message: 'Invalid input' }))
         };
       }
 
@@ -72,7 +71,7 @@ export class SlatesProviderProtoHandlerManager {
         return {
           jsonrpc: '2.0' as const,
           id: (input as any).id,
-          error: badRequestError({ message: 'Invalid jsonrpc version' }).toResponse()
+          error: toSlateErrorResponse(badRequestError({ message: 'Invalid jsonrpc version' }))
         };
       }
 
@@ -81,7 +80,7 @@ export class SlatesProviderProtoHandlerManager {
         return {
           jsonrpc: '2.0' as const,
           id: (input as any).id,
-          error: badRequestError({ message: 'Invalid or missing method' }).toResponse()
+          error: toSlateErrorResponse(badRequestError({ message: 'Invalid or missing method' }))
         };
       }
 
@@ -90,7 +89,7 @@ export class SlatesProviderProtoHandlerManager {
         return {
           jsonrpc: '2.0' as const,
           id: (input as any).id,
-          error: notFoundError('handler', input.method).toResponse()
+          error: toSlateErrorResponse(notFoundError('handler', input.method))
         };
       }
 
@@ -99,14 +98,16 @@ export class SlatesProviderProtoHandlerManager {
         return {
           jsonrpc: '2.0' as const,
           id: (input as any).id,
-          error: validationError({
-            entity: 'request',
-            message: 'Invalid request parameters',
-            errors: parsed.error.issues.map(i => ({
-              ...i,
-              path: i.path.map(p => String(p))
-            }))
-          }).toResponse()
+          error: toSlateErrorResponse(
+            validationError({
+              entity: 'request',
+              message: 'Invalid request parameters',
+              errors: parsed.error.issues.map(i => ({
+                ...i,
+                path: i.path.map(p => String(p))
+              }))
+            })
+          )
         };
       }
 
@@ -123,20 +124,16 @@ export class SlatesProviderProtoHandlerManager {
         result
       };
     } catch (err) {
-      if (isServiceError(err)) {
-        return {
-          jsonrpc: '2.0' as const,
-          id: (input as any).id,
-          error: err.toResponse()
-        };
+      if (!getSlateErrorResponse(err) && !getServiceErrorData(err)) {
+        console.error(err);
       }
 
-      console.error(err);
-
       return {
         jsonrpc: '2.0' as const,
         id: (input as any).id,
-        error: internalServerError({ message: 'Internal server error' }).toResponse()
+        error: toSlateErrorResponse(err, {
+          message: 'Internal server error'
+        })
       };
     }
   }
@@ -160,3 +157,241 @@ export let createSlatesProviderProtoHandler = (
     return manager;
   }
 });
+
+let toSlateErrorResponse = (
+  error: unknown,
+  defaults: Partial<{ code: string; message: string }> = {}
+) => {
+  let slateError = getSlateErrorResponse(error);
+  if (slateError) return slateError;
+
+  let serviceError = getServiceErrorData(error);
+  if (serviceError) {
+    return mapServiceErrorToSlateErrorResponse(serviceError, defaults);
+  }
+
+  return mapUnknownErrorToSlateErrorResponse(error, defaults);
+};
+
+let SERVICE_ERROR_CODE_MAP: Record<string, string> = {
+  invalid_data: 'input.invalid',
+  bad_request: 'request.bad',
+  not_found: 'resource.not_found',
+  unauthorized: 'auth.required',
+  forbidden: 'permission.denied',
+  invalid_version: 'request.invalid_version',
+  conflict: 'resource.conflict',
+  gone: 'resource.gone',
+  payment_required: 'payment.required',
+  precondition_failed: 'request.precondition_failed',
+  not_acceptable: 'request.not_acceptable',
+  not_implemented: 'operation.not_implemented',
+  too_many_requests: 'request.rate_limited',
+  timeout: 'internal.timeout',
+  internal_server_error: 'internal.unexpected'
+};
+
+let isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+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 } =>
+  isRecord(value) &&
+  typeof value.code === 'string' &&
+  typeof value.message === 'string' &&
+  typeof value.kind === 'string';
+
+let isServiceErrorData = (
+  value: unknown
+): value is {
+  status: number;
+  code: string;
+  message: string;
+  errors?: unknown;
+  hint?: string;
+  description?: string;
+  reason?: string;
+  [key: string]: unknown;
+} =>
+  isRecord(value) &&
+  typeof value.status === 'number' &&
+  typeof value.code === 'string' &&
+  typeof value.message === 'string' &&
+  !('config' in value) &&
+  !('request' in value) &&
+  !('response' in value) &&
+  !('isAxiosError' in value);
+
+let getSlateErrorResponse = (error: unknown) => {
+  if (
+    isStructuredValue(error) &&
+    'name' in error &&
+    typeof error.name === 'string' &&
+    error.name.startsWith('SlateError') &&
+    'toResponse' in error &&
+    typeof error.toResponse === 'function'
+  ) {
+    let response = error.toResponse();
+    return isSlateErrorPayload(response) ? response : null;
+  }
+
+  if (isSlateErrorPayload(error)) return error;
+
+  if (isStructuredValue(error) && 'data' in error && isSlateErrorPayload(error.data)) {
+    return error.data;
+  }
+
+  return null;
+};
+
+let getServiceErrorData = (error: unknown) => {
+  if (isServiceError(error) && isServiceErrorData(error.data)) {
+    return error.data;
+  }
+
+  if (isServiceErrorData(error)) return error;
+
+  if (isStructuredValue(error) && 'data' in error && isServiceErrorData(error.data)) {
+    return error.data;
+  }
+
+  if (isStructuredValue(error) && 'toResponse' in error && typeof error.toResponse === 'function') {
+    let response = error.toResponse();
+    if (isServiceErrorData(response)) return response;
+  }
+
+  return null;
+};
+
+let mapKind = (code: string) => {
+  if (code.startsWith('declaration.')) return 'declaration';
+  if (code.startsWith('input.')) return 'validation';
+  if (code.startsWith('request.')) return 'request';
+  if (code.startsWith('config.')) return 'config';
+  if (code.startsWith('auth.') || code.startsWith('permission.')) return 'auth';
+  if (code.startsWith('resource.')) return 'resource';
+  if (code.startsWith('payment.')) return 'payment';
+  if (code.startsWith('transport.')) return 'transport';
+  if (code.startsWith('upstream.')) return 'upstream';
+  return 'internal';
+};
+
+let mapRetryable = (code: string) =>
+  code === 'request.rate_limited' ||
+  code === 'upstream.rate_limited' ||
+  code === 'upstream.timeout' ||
+  code === 'upstream.network_error' ||
+  code === 'upstream.unavailable' ||
+  code === 'upstream.error' ||
+  code === 'transport.invoke_failed' ||
+  code === 'internal.timeout';
+
+let mapServiceErrorCode = (code: string, status?: number) => {
+  if (SERVICE_ERROR_CODE_MAP[code]) return SERVICE_ERROR_CODE_MAP[code];
+  if (status === 400) return 'request.bad';
+  if (status === 401) return 'auth.required';
+  if (status === 402) return 'payment.required';
+  if (status === 403) return 'permission.denied';
+  if (status === 404) return 'resource.not_found';
+  if (status === 406) return 'request.not_acceptable';
+  if (status === 409) return 'resource.conflict';
+  if (status === 410) return 'resource.gone';
+  if (status === 412) return 'request.precondition_failed';
+  if (status === 429) return 'request.rate_limited';
+  if (status === 501) return 'operation.not_implemented';
+  if (status === 504) return 'internal.timeout';
+  if (status && status >= 500) return 'internal.unexpected';
+  return 'internal.unexpected';
+};
+
+let mapIssues = (errors: unknown) => {
+  if (!Array.isArray(errors)) return undefined;
+  let issues = errors.map(error => {
+    if (!isRecord(error)) {
+      return { message: String(error) };
+    }
+
+    return {
+      ...error,
+      path: Array.isArray(error.path) ? error.path.map(entry => String(entry)) : undefined,
+      code: typeof error.code === 'string' ? error.code : undefined,
+      message: typeof error.message === 'string' ? error.message : 'Validation issue'
+    };
+  });
+  return issues.length > 0 ? issues : undefined;
+};
+
+let mapServiceErrorToSlateErrorResponse = (
+  error: {
+    status: number;
+    code: string;
+    message: string;
+    errors?: unknown;
+    hint?: string;
+    description?: string;
+    reason?: string;
+    [key: string]: unknown;
+  },
+  defaults: Partial<{ code: string; message: string }> = {}
+) => {
+  let code = defaults.code ?? mapServiceErrorCode(error.code, error.status);
+  let extraEntries = Object.entries(error).filter(
+    ([key]) =>
+      ![
+        'status',
+        'code',
+        'message',
+        'errors',
+        'hint',
+        'description',
+        'reason',
+        'object',
+        'ok'
+      ].includes(key)
+  );
+
+  return {
+    code,
+    kind: mapKind(code),
+    message: error.message,
+    retryable: mapRetryable(code),
+    status: error.status,
+    ...(mapIssues(error.errors) ? { issues: mapIssues(error.errors) } : {}),
+    baggage: {
+      serviceError: {
+        code: error.code,
+        status: error.status,
+        hint: error.hint,
+        description: error.description,
+        reason: error.reason
+      },
+      ...(extraEntries.length > 0
+        ? { serviceErrorData: Object.fromEntries(extraEntries) }
+        : {})
+    }
+  };
+};
+
+let mapUnknownErrorToSlateErrorResponse = (
+  error: unknown,
+  defaults: Partial<{ code: string; message: string }> = {}
+) => ({
+  code: defaults.code ?? 'internal.unexpected',
+  kind: 'internal',
+  message:
+    defaults.message ??
+    (error instanceof Error ? error.message : 'An unexpected internal error occurred.'),
+  retryable: false,
+  status: 500,
+  ...(error instanceof Error
+    ? {
+        baggage: {
+          originalName: error.name
+        }
+      }
+    : {})
+});

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from './handler';
 export * from './messages';
 export * from './types';
+export * from './version';

package/src/messages/action.ts

@@ -1,5 +1,6 @@
 import z from 'zod';
 import { slatesAction } from '../types';
+import { withRequestTraces } from './tracing';
 
 /**
  * List Actions
@@ -69,7 +70,7 @@ export type SlatesMessageActionInvokeRequest = z.infer<
 export let slatesMessageActionInvokeResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     output: z.record(z.string(), z.any()),
     message: z.string().optional()
   })
@@ -99,7 +100,7 @@ export type SlatesMessageActionTriggerEventMapRequest = z.infer<
 export let slatesMessageActionTriggerEventMapResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     type: z.string(),
     id: z.string(),
     output: z.record(z.string(), z.any())
@@ -130,7 +131,7 @@ export type SlatesMessageActionTriggerEventsPollRequest = z.infer<
 export let slatesMessageActionTriggerEventsPollResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     inputs: z.array(z.record(z.string(), z.any())),
     updatedState: z.any().nullable().optional()
   })
@@ -169,7 +170,7 @@ export type SlatesMessageActionTriggerWebhookHandleRequest = z.infer<
 export let slatesMessageActionTriggerWebhookHandleResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     inputs: z.array(z.record(z.string(), z.any())),
     updatedState: z.any().nullable().optional()
   })
@@ -199,7 +200,7 @@ export type SlatesMessageActionTriggerWebhookRegisterRequest = z.infer<
 export let slatesMessageActionTriggerWebhookRegisterResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     registrationDetails: z.any(),
     state: z.any().optional()
   })
@@ -231,7 +232,7 @@ export type SlatesMessageActionTriggerWebhookUnregisterRequest = z.infer<
 export let slatesMessageActionTriggerWebhookUnregisterResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({})
+  result: withRequestTraces({})
 });
 
 export type SlatesMessageActionTriggerWebhookUnregisterResponse = z.infer<

package/src/messages/auth.ts

@@ -1,5 +1,6 @@
 import z from 'zod';
 import { slatesAuthenticationMethod } from '../types';
+import { withRequestTraces } from './tracing';
 
 /**
  * Set Authentication
@@ -92,7 +93,7 @@ export type SlatesMessageAuthInputChangedRequest = z.infer<
 export let slatesMessageAuthInputChangedResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     input: z.record(z.string(), z.any()).optional()
   })
 });
@@ -120,7 +121,7 @@ export type SlatesMessageAuthDefaultInputGetRequest = z.infer<
 export let slatesMessageAuthDefaultInputGetResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     input: z.record(z.string(), z.any())
   })
 });
@@ -155,7 +156,7 @@ export type SlatesMessageAuthAuthorizationUrlGetRequest = z.infer<
 export let slatesMessageAuthAuthorizationUrlGetResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     authorizationUrl: z.string(),
     input: z.record(z.string(), z.any()).optional(),
     callbackState: z.record(z.string(), z.any()).optional()
@@ -194,9 +195,10 @@ export type SlatesMessageAuthAuthorizationCallbackHandleRequest = z.infer<
 export let slatesMessageAuthAuthorizationCallbackHandleResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     output: z.record(z.string(), z.any()),
-    input: z.record(z.string(), z.any()).optional()
+    input: z.record(z.string(), z.any()).optional(),
+    scopes: z.array(z.string()).optional()
   })
 });
 
@@ -229,7 +231,7 @@ export type SlatesMessageAuthTokenRefreshHandleRequest = z.infer<
 export let slatesMessageAuthTokenRefreshHandleResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     output: z.record(z.string(), z.any()),
     input: z.record(z.string(), z.any()).optional()
   })
@@ -262,7 +264,7 @@ export type SlatesMessageAuthProfileGetRequest = z.infer<
 export let slatesMessageAuthProfileGetResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     profile: z.record(z.string(), z.any())
   })
 });
@@ -292,7 +294,7 @@ export type SlatesMessageAuthOutputGetRequest = z.infer<
 export let slatesMessageAuthOutputGetResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     output: z.record(z.string(), z.any())
   })
 });

package/src/messages/config.ts

@@ -1,4 +1,5 @@
 import z from 'zod';
+import { withRequestTraces } from './tracing';
 
 /**
  * Set Config
@@ -61,7 +62,7 @@ export type SlatesMessageConfigChangedRequest = z.infer<
 export let slatesMessageConfigChangedResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     success: z.boolean(),
     config: z.record(z.string(), z.any()).optional(),
     errors: z
@@ -97,7 +98,7 @@ export type SlatesMessageConfigDefaultGetRequest = z.infer<
 export let slatesMessageConfigDefaultGetResponse = z.object({
   jsonrpc: z.literal('2.0'),
   id: z.string(),
-  result: z.object({
+  result: withRequestTraces({
     config: z.record(z.string(), z.any()).nullable()
   })
 });

package/src/messages/controlFlow.ts

@@ -1,11 +1,12 @@
 import z from 'zod';
 import { slatesParticipant } from '../types';
+import { SLATES_PROTOCOL_VERSION } from '../version';
 
 export let slatesMessageHelloNotification = z.object({
   jsonrpc: z.literal('2.0'),
   method: z.literal('slates/hello'),
   params: z.object({
-    protocol: z.literal('slates@2026-01-01')
+    protocol: z.literal(SLATES_PROTOCOL_VERSION)
   })
 });