@slates/client 1.0.0-rc.2

package/src/client.ts

@@ -0,0 +1,367 @@
+import {
+  SLATES_PROTOCOL_VERSION,
+  SlateAuthenticationMethod,
+  SlatesAction,
+  SlatesParticipant,
+  slatesRequestsByMethod,
+  slatesResponsesByMethod
+} from '@slates/proto';
+import { randomUUID } from 'crypto';
+import z from 'zod';
+import { SlateProtocolError } from './error';
+import { SlatesClientState, SlatesProtocolClientOptions } from './types';
+
+let createDefaultParticipants = (): SlatesParticipant[] => [
+  {
+    type: 'consumer',
+    id: 'slates-client',
+    name: 'Slates Client'
+  }
+];
+
+export class SlatesProtocolClient {
+  readonly transport: SlatesProtocolClientOptions['transport'];
+  state: SlatesClientState;
+
+  constructor(opts: SlatesProtocolClientOptions) {
+    this.transport = opts.transport;
+    this.state = {
+      protocol: SLATES_PROTOCOL_VERSION,
+      participants: opts.participants ?? createDefaultParticipants(),
+      config: opts.state?.config ?? null,
+      auth: opts.state?.auth ?? null,
+      session: opts.state?.session ?? null
+    };
+  }
+
+  setParticipants(participants: SlatesParticipant[]) {
+    this.state.participants = participants;
+    return this;
+  }
+
+  setConfig(config: Record<string, any> | null) {
+    this.state.config = config;
+    return this;
+  }
+
+  setAuth(auth: SlatesClientState['auth']) {
+    this.state.auth = auth;
+    return this;
+  }
+
+  clearAuth() {
+    this.state.auth = null;
+    return this;
+  }
+
+  setSession(session: SlatesClientState['session']) {
+    this.state.session = session;
+    return this;
+  }
+
+  ensureSession() {
+    if (!this.state.session) {
+      this.state.session = {
+        id: randomUUID(),
+        state: {}
+      };
+    }
+
+    return this.state.session;
+  }
+
+  private buildStateMessages() {
+    return [
+      {
+        jsonrpc: '2.0' as const,
+        method: 'slates/hello' as const,
+        params: { protocol: this.state.protocol }
+      },
+      {
+        jsonrpc: '2.0' as const,
+        method: 'slates/participant.set' as const,
+        params: { participants: this.state.participants }
+      },
+      ...(this.state.config
+        ? [
+            {
+              jsonrpc: '2.0' as const,
+              method: 'slates/config.set' as const,
+              params: { config: this.state.config }
+            }
+          ]
+        : []),
+      ...(this.state.auth
+        ? [
+            {
+              jsonrpc: '2.0' as const,
+              method: 'slates/auth.set' as const,
+              params: {
+                authenticationMethodId: this.state.auth.authenticationMethodId,
+                output: this.state.auth.output
+              }
+            }
+          ]
+        : []),
+      ...(this.state.session
+        ? [
+            {
+              jsonrpc: '2.0' as const,
+              method: 'slates/session.start' as const,
+              params: {
+                sessionId: this.state.session.id,
+                state: this.state.session.state
+              }
+            }
+          ]
+        : [])
+    ];
+  }
+
+  async request<Key extends keyof typeof slatesRequestsByMethod>(
+    method: Key,
+    params: z.infer<(typeof slatesRequestsByMethod)[Key]>['params']
+  ): Promise<z.infer<(typeof slatesResponsesByMethod)[Key]>['result']> {
+    let id = randomUUID();
+    let responses = await this.transport.send([
+      ...this.buildStateMessages(),
+      {
+        jsonrpc: '2.0',
+        id,
+        method,
+        params
+      } as z.infer<(typeof slatesRequestsByMethod)[Key]>
+    ]);
+
+    let response = responses.find(message => 'id' in message && message.id === id) as
+      | { result?: any; error?: any }
+      | undefined;
+
+    if (!response) {
+      throw new Error(`No response was returned for method ${String(method)}.`);
+    }
+
+    if (response.error) {
+      throw SlateProtocolError.fromResponse(response.error);
+    }
+
+    return response.result;
+  }
+
+  async identify() {
+    return this.request('slates/provider.identify', {});
+  }
+
+  async listActions() {
+    return this.request('slates/actions.list', {});
+  }
+
+  async listTools(): Promise<SlatesAction[]> {
+    let result = await this.listActions();
+    return result.actions.filter(action => action.type === 'action.tool');
+  }
+
+  async listTriggers(): Promise<SlatesAction[]> {
+    let result = await this.listActions();
+    return result.actions.filter(action => action.type === 'action.trigger');
+  }
+
+  async getAction(actionId: string) {
+    return this.request('slates/action.get', { actionId });
+  }
+
+  async getTool(actionId: string) {
+    let result = await this.getAction(actionId);
+    if (result.action.type !== 'action.tool') {
+      throw new Error(`Action ${actionId} is not a tool.`);
+    }
+
+    return result.action;
+  }
+
+  async getTrigger(actionId: string) {
+    let result = await this.getAction(actionId);
+    if (result.action.type !== 'action.trigger') {
+      throw new Error(`Action ${actionId} is not a trigger.`);
+    }
+
+    return result.action;
+  }
+
+  async getConfigSchema() {
+    return this.request('slates/config.schema.get', {});
+  }
+
+  async getDefaultConfig() {
+    return this.request('slates/config.get_default', {});
+  }
+
+  async updateConfig(
+    previousConfig: Record<string, any> | null,
+    newConfig: Record<string, any>
+  ) {
+    return this.request('slates/config.changed', {
+      previousConfig,
+      newConfig
+    });
+  }
+
+  async listAuthMethods(): Promise<{ authenticationMethods: SlateAuthenticationMethod[] }> {
+    return this.request('slates/auth.methods.list', {});
+  }
+
+  async getAuthMethod(authenticationMethodId: string) {
+    return this.request('slates/auth.method.get', {
+      authenticationMethodId
+    });
+  }
+
+  async getDefaultAuthInput(authenticationMethodId: string) {
+    return this.request('slates/auth.input.get_default', {
+      authenticationMethodId
+    });
+  }
+
+  async updateAuthInput(d: {
+    authenticationMethodId: string;
+    previousInput: Record<string, any> | null;
+    newInput: Record<string, any>;
+  }) {
+    return this.request('slates/auth.input.changed', {
+      authenticationMethodId: d.authenticationMethodId,
+      previousInput: d.previousInput,
+      newInput: d.newInput
+    });
+  }
+
+  async getAuthOutput(d: { authenticationMethodId: string; input: Record<string, any> }) {
+    return this.request('slates/auth.output.get', {
+      authenticationMethodId: d.authenticationMethodId,
+      input: d.input
+    });
+  }
+
+  async getAuthorizationUrl(d: {
+    authenticationMethodId: string;
+    redirectUri: string;
+    state: string;
+    input: Record<string, any>;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+  }) {
+    return this.request('slates/auth.authorization_url.get', d);
+  }
+
+  async handleAuthorizationCallback(d: {
+    authenticationMethodId: string;
+    code: string;
+    state: string;
+    redirectUri: string;
+    input: Record<string, any>;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+    callbackState?: Record<string, any>;
+  }): Promise<{
+    output: Record<string, any>;
+    input?: Record<string, any>;
+    scopes?: string[];
+  }> {
+    return this.request('slates/auth.authorization_callback.handle', d);
+  }
+
+  async refreshToken(d: {
+    authenticationMethodId: string;
+    output: Record<string, any>;
+    input: Record<string, any>;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+  }) {
+    return this.request('slates/auth.token_refresh.handle', d);
+  }
+
+  async getAuthProfile(d: {
+    authenticationMethodId: string;
+    output: Record<string, any>;
+    input: Record<string, any>;
+    scopes: string[];
+  }) {
+    return this.request('slates/auth.profile.get', d);
+  }
+
+  async invokeTool(actionId: string, input: Record<string, any>) {
+    this.ensureSession();
+    return this.request('slates/action.tool.invoke', {
+      actionId,
+      input
+    });
+  }
+
+  async mapTriggerEvent(actionId: string, input: Record<string, any>) {
+    this.ensureSession();
+    return this.request('slates/action.trigger.map_event', {
+      actionId,
+      input
+    });
+  }
+
+  async registerTriggerWebhook(actionId: string, webhookBaseUrl: string) {
+    this.ensureSession();
+    return this.request('slates/action.trigger.webhook_register', {
+      actionId,
+      webhookBaseUrl
+    });
+  }
+
+  async handleTriggerWebhook(d: {
+    actionId: string;
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array | null;
+    state?: any;
+  }) {
+    this.ensureSession();
+    let encodedBody =
+      typeof d.body === 'string'
+        ? Buffer.from(d.body, 'utf-8').toString('base64')
+        : d.body
+          ? Buffer.from(d.body).toString('base64')
+          : null;
+
+    return this.request('slates/action.trigger.webhook_handle', {
+      actionId: d.actionId,
+      url: d.url,
+      method: d.method,
+      headers: d.headers ?? {},
+      body: encodedBody
+        ? {
+            encoding: 'base64',
+            content: encodedBody
+          }
+        : null,
+      state: d.state ?? null
+    });
+  }
+
+  async unregisterTriggerWebhook(d: {
+    actionId: string;
+    webhookBaseUrl: string;
+    registrationDetails: any;
+    state?: any;
+  }) {
+    this.ensureSession();
+    return this.request('slates/action.trigger.webhook_unregister', {
+      actionId: d.actionId,
+      webhookBaseUrl: d.webhookBaseUrl,
+      registrationDetails: d.registrationDetails,
+      state: d.state ?? null
+    });
+  }
+
+  async close() {
+    await this.transport.close?.();
+  }
+}

package/src/error.ts

@@ -0,0 +1,157 @@
+export type SlateProtocolErrorSource = 'provider' | 'transport';
+
+export type SlateProtocolErrorKind =
+  | 'declaration'
+  | 'validation'
+  | 'request'
+  | 'auth'
+  | 'config'
+  | 'resource'
+  | 'payment'
+  | 'upstream'
+  | 'transport'
+  | 'internal';
+
+export interface SlateProtocolErrorResponse {
+  code: string;
+  message: string;
+  kind: SlateProtocolErrorKind;
+  retryable?: boolean;
+  status?: number;
+  issues?: Array<Record<string, unknown>>;
+  provider?: Record<string, unknown>;
+  upstream?: Record<string, unknown>;
+  baggage?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+let isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+let isSlateErrorResponse = (error: unknown): error is SlateProtocolErrorResponse =>
+  isRecord(error) && typeof error.code === 'string' && typeof error.message === 'string';
+
+let inferKindFromCode = (code: string): SlateProtocolErrorKind => {
+  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 normalizeResponse = (
+  error: unknown,
+  source: SlateProtocolErrorSource,
+  defaults: Partial<SlateProtocolErrorResponse> = {}
+): SlateProtocolErrorResponse => {
+  if (isSlateErrorResponse(error)) {
+    return {
+      ...defaults,
+      ...error,
+      kind: error.kind ?? inferKindFromCode(error.code)
+    };
+  }
+
+  if (isRecord(error) && typeof error.message === 'string') {
+    let code =
+      typeof error.code === 'string'
+        ? error.code
+        : defaults.code ?? (source === 'transport' ? 'transport.invoke_failed' : 'internal.unexpected');
+
+    return {
+      ...defaults,
+      ...error,
+      code,
+      message: error.message,
+      kind:
+        (typeof error.kind === 'string' ? (error.kind as SlateProtocolErrorKind) : defaults.kind) ??
+        inferKindFromCode(code)
+    };
+  }
+
+  let code =
+    defaults.code ?? (source === 'transport' ? 'transport.invoke_failed' : 'internal.unexpected');
+
+  return {
+    ...defaults,
+    code,
+    message:
+      error instanceof Error
+        ? error.message
+        : defaults.message ?? 'The slate returned an unexpected error.',
+    kind: defaults.kind ?? inferKindFromCode(code),
+    baggage: {
+      ...(defaults.baggage ?? {}),
+      ...(error instanceof Error
+        ? { originalName: error.name }
+        : { originalValue: error })
+    }
+  };
+};
+
+export class SlateProtocolError extends Error {
+  cause?: unknown;
+  data: SlateProtocolErrorResponse;
+  source: SlateProtocolErrorSource;
+
+  constructor(
+    data: SlateProtocolErrorResponse,
+    source: SlateProtocolErrorSource = 'provider',
+    cause?: unknown
+  ) {
+    super(data.message);
+    this.name = 'SlateProtocolError';
+    this.data = data;
+    this.source = source;
+    this.cause = cause;
+  }
+
+  get code() {
+    return this.data.code;
+  }
+
+  get kind() {
+    return this.data.kind;
+  }
+
+  get retryable() {
+    return this.data.retryable;
+  }
+
+  get status() {
+    return this.data.status;
+  }
+
+  toJSON() {
+    return {
+      ...this.data,
+      source: this.source
+    };
+  }
+
+  static is(error: unknown): error is SlateProtocolError {
+    return error instanceof SlateProtocolError;
+  }
+
+  static fromResponse(
+    error: unknown,
+    source: SlateProtocolErrorSource = 'provider'
+  ): SlateProtocolError {
+    if (SlateProtocolError.is(error)) return error;
+    return new SlateProtocolError(normalizeResponse(error, source), source, error);
+  }
+
+  static fromUnknown(
+    error: unknown,
+    defaults: Partial<SlateProtocolErrorResponse> = {},
+    source: SlateProtocolErrorSource = 'transport'
+  ) {
+    if (SlateProtocolError.is(error)) return error;
+    return new SlateProtocolError(normalizeResponse(error, source, defaults), source, error);
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+import { SlatesProtocolClient } from './client';
+import { SlatesProtocolClientOptions } from './types';
+
+export * from './client';
+export * from './error';
+export * from './transport';
+export * from './types';
+
+export let createSlatesClient = (opts: SlatesProtocolClientOptions) =>
+  new SlatesProtocolClient(opts);

package/src/transport.ts

@@ -0,0 +1,57 @@
+import {
+  SlatesNotifications,
+  SlatesProviderProtoHandlerManager,
+  SlatesRequests,
+  SlatesResponses
+} from '@slates/proto';
+import { Slate, SlateLogListener } from '@slates/provider';
+import { createProviderHandler } from '@slates/provider-handler';
+import { SlateProtocolError } from './error';
+import { SlatesMessageTransport } from './types';
+
+type ProviderMessage = SlatesNotifications | SlatesRequests;
+type ProviderResponse = SlatesNotifications | SlatesResponses;
+
+let toTransportError = (value: unknown, defaultMessage: string) =>
+  SlateProtocolError.fromUnknown(
+    value,
+    {
+      code: 'transport.invoke_failed',
+      kind: 'transport',
+      message: defaultMessage,
+      retryable: true,
+      baggage: {
+        response: value as any
+      }
+    },
+    'transport'
+  );
+
+export let createLocalSlateTransport = <ConfigType extends {}, AuthType extends {}>(d: {
+  slate: Slate<ConfigType, AuthType>;
+  listeners?: SlateLogListener[];
+}): SlatesMessageTransport => {
+  let managerPromise = createProviderHandler(d.slate, d.listeners ?? []).run();
+
+  return {
+    async send(messages) {
+      let manager = await managerPromise;
+      let responses: ProviderResponse[] = [];
+
+      for (let message of messages as ProviderMessage[]) {
+        let response;
+        try {
+          response = await SlatesProviderProtoHandlerManager.handleInput(manager, message);
+        } catch (error) {
+          throw toTransportError(error, 'Local slate invocation failed');
+        }
+
+        if (response) {
+          responses.push(response as ProviderResponse);
+        }
+      }
+
+      return responses;
+    }
+  };
+};

package/src/types.ts

@@ -0,0 +1,36 @@
+import {
+  SlatesNotifications,
+  SlatesParticipant,
+  SlatesProtocolVersion,
+  SlatesRequests,
+  SlatesResponses
+} from '@slates/proto';
+
+export type SlatesJsonObject = Record<string, any>;
+export type SlatesProtocolMessage = SlatesNotifications | SlatesRequests;
+export type SlatesProtocolResponse = SlatesNotifications | SlatesResponses;
+
+export interface SlatesClientState {
+  protocol: SlatesProtocolVersion;
+  participants: SlatesParticipant[];
+  config: SlatesJsonObject | null;
+  auth: {
+    authenticationMethodId: string;
+    output: SlatesJsonObject;
+  } | null;
+  session: {
+    id: string;
+    state: SlatesJsonObject;
+  } | null;
+}
+
+export interface SlatesMessageTransport {
+  send(messages: SlatesProtocolMessage[]): Promise<SlatesProtocolResponse[]>;
+  close?(): Promise<void> | void;
+}
+
+export interface SlatesProtocolClientOptions {
+  transport: SlatesMessageTransport;
+  participants?: SlatesParticipant[];
+  state?: Partial<SlatesClientState>;
+}