@spekoai/sdk 0.4.3 → 0.5.2

package/src/index.ts

@@ -0,0 +1,212 @@
+export { Speko } from './lib/client.js';
+export { SpekoApiError, SpekoAuthError, SpekoRateLimitError } from './lib/errors.js';
+export type {
+  AgentAmbientClip,
+  AgentBackgroundAudio,
+  AgentCallListEntry,
+  AgentCallListPage,
+  AgentCallListParams,
+  AgentCreateParams,
+  AgentExtractionField,
+  AgentIntent,
+  AgentLifecycleWebhookCreate,
+  AgentLifecycleWebhookSerialized,
+  AgentLifecycleWebhookUpdate,
+  AgentLlmOptions,
+  AgentRow,
+  AgentStackPreferences,
+  AgentSttOptions,
+  AgentToolCreateParams,
+  AgentToolRow,
+  AgentToolSourceBuiltin,
+  AgentToolSourceCreate,
+  AgentToolSourceInline,
+  AgentToolSourceIntegration,
+  AgentToolSourceSerialized,
+  AgentToolSourceUpdate,
+  AgentToolSourceWebhookCreate,
+  AgentToolSourceWebhookSerialized,
+  AgentToolSourceWebhookUpdate,
+  AgentToolUpdateParams,
+  AgentUpdateParams,
+  AgentWebhookAuthHeader,
+  AgentWebhookAuthHeaderInput,
+  AgentWebhooksCreate,
+  AgentWebhooksSerialized,
+  AgentWebhooksUpdate,
+  AvailablePhoneNumber,
+  BlindTransferParams,
+  CallControlDialParams,
+  CallControlDialResult,
+  CallControlListParams,
+  CallCostLine,
+  CallDetail,
+  CallEvent,
+  CallRecording,
+  CallReport,
+  CallReportWebhookDelivery,
+  CallTranscriptEntry,
+  CallTransfer,
+  CallTransferResponse,
+  CancelScheduledCallbackParams,
+  CancelWarmTransferParams,
+  ChatMessage,
+  ChatTool,
+  ChatToolCall,
+  ChatToolChoice,
+  ChatToolExecutionMode,
+  ChatToolSource,
+  CompleteParams,
+  CompleteResult,
+  CompleteStreamEvent,
+  CompleteWarmTransferParams,
+  CreditLedgerEntry,
+  CreditLedgerKind,
+  CreditLedgerPage,
+  CreditLedgerQueryParams,
+  EndCallResult,
+  FinalizeCallReportParams,
+  FinalizeCallReportResult,
+  KeySource,
+  KnowledgeBaseCreateParams,
+  KnowledgeBaseDocumentCreateParams,
+  KnowledgeBaseDocumentCreateResult,
+  KnowledgeBaseDocumentPollOptions,
+  KnowledgeBaseDocumentRow,
+  KnowledgeBaseDocumentStatus,
+  KnowledgeBaseDocumentUploadParams,
+  KnowledgeBaseDocumentUploadSpec,
+  KnowledgeBaseListParams,
+  KnowledgeBaseRow,
+  OptimizeFor,
+  OrganizationBalance,
+  PhoneNumberCreateParams,
+  PhoneNumberDirection,
+  PhoneNumberImportSipTrunkParams,
+  PhoneNumberKybAttestationContract,
+  PhoneNumberKybAttestor,
+  PhoneNumberKybAuthorizedRepresentative,
+  PhoneNumberKybBusinessProfile,
+  PhoneNumberKybDeclaration,
+  PhoneNumberKybDraftParams,
+  PhoneNumberKybOverview,
+  PhoneNumberKybSlackNotificationStatus,
+  PhoneNumberKybStatus,
+  PhoneNumberKybSubmission,
+  PhoneNumberKybSubmissionStatus,
+  PhoneNumberKybSubmitParams,
+  PhoneNumberRow,
+  PhoneNumberSearchParams,
+  PhoneNumberSetupStatus,
+  PhoneNumberSmsAssignmentStatus,
+  PhoneNumberSource,
+  PhoneNumberUpdateParams,
+  PipelineConstraints,
+  RealtimeConnectParams,
+  RealtimeEventHandler,
+  RealtimeFrame,
+  RealtimeProvider,
+  RealtimeSessionHandle,
+  RealtimeToolSpec,
+  RoutingIntent,
+  ScheduledCallback,
+  ScheduledCallbackStatus,
+  ScheduledCallbacksListParams,
+  SessionStreamEvent,
+  SessionStreamOptions,
+  SessionTranscript,
+  SessionTranscriptEntry,
+  SmsBatch,
+  SmsBatchCreateParams,
+  SmsBatchRecipient,
+  SmsConsent,
+  SmsConsentInput,
+  SmsConsentListParams,
+  SmsConsentSource,
+  SmsConversation,
+  SmsConversationListParams,
+  SmsConversationNote,
+  SmsConversationSendParams,
+  SmsConversationUpdate,
+  SmsMessage,
+  SmsMessageDirection,
+  SmsMessageListParams,
+  SmsMessageOrigin,
+  SmsMessageStatus,
+  SmsPage,
+  SmsSegmentEstimate,
+  SmsSendParams,
+  SmsSettings,
+  SmsSettingsUpdate,
+  SmsStreamEvent,
+  SmsSuppression,
+  SpekoClientOptions,
+  SynthesizeOptions,
+  SynthesizeResult,
+  SynthesizeStreamResult,
+  TranscribeOptions,
+  TranscribeResult,
+  TranscribeStreamEvent,
+  UsageByProvider,
+  UsageQueryParams,
+  UsageSummary,
+  VoiceCatalogEntry,
+  VoiceDialParams,
+  VoiceDialResult,
+  VoicesListParams,
+  VoicesListResult,
+  VoicesProviderEntry,
+  WarmTransferDestination,
+  WarmTransferFallback,
+  WarmTransferFallbackResult,
+  WarmTransferParams,
+  WarmTransferVoicemailDetection,
+  WebhookDelivery,
+  WebhookDeliveryAttempt,
+  WebhookDeliveryDetail,
+  WebhookDeliveryEndpointOption,
+  WebhookDeliveryListParams,
+  WebhookDeliveryPage,
+  WebhookDeliveryStatus,
+  WebhookEndpoint,
+  WebhookEndpointAuthHeaderInput,
+  WebhookEndpointAuthHeaderUpdate,
+  WebhookEndpointInput,
+  WebhookEndpointUpdate,
+  WebhookEventType,
+  WebJoinParams,
+  WebJoinResult,
+  WorkspaceWebhookEventType,
+} from './lib/types/index.js';
+export type {
+  BridgeCommandPayload,
+  BrokerPresenceResource,
+  BrokerPresenceStatus,
+  CallCommand,
+  CallCommandPayload,
+  CallCommandResult,
+  CallDirection,
+  CallEventNotice,
+  CallEventResource,
+  CallEventType,
+  CallJoinCredentials,
+  CallLegKind,
+  CallLegResource,
+  CallLegStatus,
+  CallResource,
+  CallStatus,
+  DtmfCommandPayload,
+  HangupCommandPayload,
+  PresenceMessage,
+  RingOffer,
+  TransferCommandPayload,
+  VoiceErrorCode,
+} from './lib/voice-contract.js';
+export {
+  BROKER_ID_PATTERN,
+  CALL_COMMANDS,
+  CALL_EVENTS,
+  DTMF_PATTERN,
+  PRESENCE_STALE_AFTER_MS,
+  VOICE_ERROR_CODES,
+} from './lib/voice-contract.js';

package/src/lib/client.ts

@@ -0,0 +1,169 @@
+import { HttpClient } from './http.js';
+import { Agents } from './resources/agents.js';
+import { Callbacks } from './resources/callbacks.js';
+import { Calls } from './resources/calls.js';
+import { Complete } from './resources/complete.js';
+import { Credits } from './resources/credits.js';
+import { KnowledgeBases } from './resources/knowledge-bases.js';
+import { PhoneNumbers } from './resources/phone-numbers.js';
+import { Realtime } from './resources/realtime.js';
+import { Sessions } from './resources/sessions.js';
+import { Sms } from './resources/sms.js';
+import { Synthesize } from './resources/synthesize.js';
+import { Transcribe } from './resources/transcribe.js';
+import { Usage } from './resources/usage.js';
+import { CallControl, Voice } from './resources/voice.js';
+import { Voices } from './resources/voices.js';
+import { Webhooks } from './resources/webhooks.js';
+import type {
+  CompleteParams,
+  CompleteResult,
+  CompleteStreamEvent,
+  SpekoClientOptions,
+  SynthesizeOptions,
+  SynthesizeResult,
+  SynthesizeStreamResult,
+  TranscribeOptions,
+  TranscribeResult,
+  TranscribeStreamEvent,
+} from './types/index.js';
+import { BROKER_ID_PATTERN } from './voice-contract.js';
+
+const DEFAULT_BASE_URL = 'https://api.speko.dev';
+const DEFAULT_TIMEOUT = 30_000;
+
+/**
+ * Speko client — one API, every voice provider.
+ *
+ * @example
+ * ```ts
+ * import { Speko } from '@spekoai/sdk';
+ *
+ * const speko = new Speko({ apiKey: process.env.SPEKO_API_KEY });
+ *
+ * const { text, provider } = await speko.transcribe(audioBytes, {
+ *   language: 'es-MX',
+ * });
+ * ```
+ */
+export class Speko {
+  readonly usage: Usage;
+  readonly credits: Credits;
+  readonly realtime: Realtime;
+  readonly voice: Voice;
+  /**
+   * Programmable voice: `controlId`-addressed call control for human calls,
+   * plus broker presence. See {@link CallControl} for the Telnyx Call Control
+   * mapping — including where it deliberately differs.
+   */
+  readonly callControl: CallControl;
+  readonly voices: Voices;
+  readonly phoneNumbers: PhoneNumbers;
+  readonly agents: Agents;
+  readonly knowledgeBases: KnowledgeBases;
+  readonly calls: Calls;
+  readonly callbacks: Callbacks;
+  readonly sessions: Sessions;
+  readonly webhooks: Webhooks;
+  readonly sms: Sms;
+
+  private readonly transcribeResource: Transcribe;
+  private readonly synthesizeResource: Synthesize;
+  private readonly completeResource: Complete;
+
+  constructor(options: SpekoClientOptions) {
+    if (!options.apiKey) {
+      throw new Error(
+        'Speko: apiKey is required. Get one at https://platform.speko.dev/agents/keys',
+      );
+    }
+    if (options.brokerId !== undefined && !BROKER_ID_PATTERN.test(options.brokerId)) {
+      throw new Error(
+        'Speko: brokerId must start with a letter or digit and contain only letters, digits, dot, underscore, or hyphen (max 128 characters)',
+      );
+    }
+
+    const http = new HttpClient({
+      baseUrl: options.baseUrl ?? options.baseURL ?? DEFAULT_BASE_URL,
+      apiKey: options.apiKey,
+      timeout: options.timeout ?? DEFAULT_TIMEOUT,
+    });
+
+    this.usage = new Usage(http);
+    this.credits = new Credits(http);
+    this.realtime = new Realtime(http);
+    this.voice = new Voice(http);
+    this.callControl = new CallControl(http, options.brokerId);
+    this.voices = new Voices(http);
+    this.phoneNumbers = new PhoneNumbers(http);
+    this.agents = new Agents(http);
+    this.knowledgeBases = new KnowledgeBases(http);
+    this.calls = new Calls(http);
+    this.callbacks = new Callbacks(http);
+    this.sessions = new Sessions(http);
+    this.webhooks = new Webhooks(http);
+    this.sms = new Sms(http);
+    this.transcribeResource = new Transcribe(http);
+    this.synthesizeResource = new Synthesize(http);
+    this.completeResource = new Complete(http);
+  }
+
+  /**
+   * Transcribe audio. The router picks the best STT provider for your
+   * `(language, region, optimizeFor)` and fails over automatically.
+   *
+   * Pass an `AbortSignal` to cancel the in-flight request — useful when a
+   * calling framework (e.g. LiveKit Agents) tears down a session mid-call.
+   */
+  transcribe(
+    audio: Uint8Array,
+    options: TranscribeOptions,
+    abortSignal?: AbortSignal,
+  ): Promise<TranscribeResult> {
+    return this.transcribeResource.call(audio, options, abortSignal);
+  }
+
+  transcribeStream(
+    audio: Uint8Array,
+    options: TranscribeOptions,
+    abortSignal?: AbortSignal,
+  ): AsyncIterableIterator<TranscribeStreamEvent> {
+    return this.transcribeResource.stream(audio, options, abortSignal);
+  }
+
+  /**
+   * Synthesize text into audio. The router picks the best TTS provider and
+   * fails over automatically. The result includes the audio bytes plus the
+   * provider's native content type.
+   */
+  synthesize(
+    text: string,
+    options: SynthesizeOptions,
+    abortSignal?: AbortSignal,
+  ): Promise<SynthesizeResult> {
+    return this.synthesizeResource.call(text, options, abortSignal);
+  }
+
+  synthesizeStream(
+    text: string,
+    options: SynthesizeOptions,
+    abortSignal?: AbortSignal,
+  ): Promise<SynthesizeStreamResult> {
+    return this.synthesizeResource.stream(text, options, abortSignal);
+  }
+
+  /**
+   * Run an LLM completion. The router picks the best LLM provider and fails
+   * over automatically.
+   */
+  complete(params: CompleteParams, abortSignal?: AbortSignal): Promise<CompleteResult> {
+    return this.completeResource.call(params, abortSignal);
+  }
+
+  completeStream(
+    params: CompleteParams,
+    abortSignal?: AbortSignal,
+  ): AsyncIterableIterator<CompleteStreamEvent> {
+    return this.completeResource.stream(params, abortSignal);
+  }
+}

package/src/lib/errors.ts

@@ -0,0 +1,28 @@
+export class SpekoApiError extends Error {
+  readonly status: number;
+  readonly code: string;
+
+  constructor(message: string, status: number, code: string) {
+    super(message);
+    this.name = 'SpekoApiError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export class SpekoAuthError extends SpekoApiError {
+  constructor(message = 'Invalid or missing API key') {
+    super(message, 401, 'AUTH_ERROR');
+    this.name = 'SpekoAuthError';
+  }
+}
+
+export class SpekoRateLimitError extends SpekoApiError {
+  readonly retryAfter: number | null;
+
+  constructor(message = 'Rate limit exceeded', retryAfter: number | null = null) {
+    super(message, 429, 'RATE_LIMITED');
+    this.name = 'SpekoRateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}