@superdurable/connector-twilio-messaging 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,283 @@
1
+ import { ProviderRequest, ProviderResponse } from '@superdurable/connectors-sdk/providerhttp';
2
+ import * as _superdurable_connectors_sdk from '@superdurable/connectors-sdk';
3
+ import { Query, Mutation, Call, MutationAttempt, QueryAttempt, CredentialProvider, Failure, ReceiptDraft, QueryStepConfig, QueryResult, QueryStep, MutationStepConfig, MutationResult, MutationStep, QueryDefinition, MutationDefinition, ConnectorConfigurationUI, TriggerTarget, TriggerLogger, TriggerDefinition, TriggerBindingDefinition, TriggerRunner } from '@superdurable/connectors-sdk';
4
+ import { G as GetMessageInput, M as Message, S as SendMessageInput, C as Config, a as Credentials, b as Connection } from './connection-BQ9-3dhC.js';
5
+ export { c as ConfigSchema, d as GetMessageInputSchema, e as MessageSchema, f as SendMessageInputSchema, g as decodeCredentials, n as newConnectionWithOperations } from './connection-BQ9-3dhC.js';
6
+ import { LoadedProject } from '@superdurable/connectors-sdk/projectconfig';
7
+ import { StepTarget } from '@superdurable/dex';
8
+ import { CursorStore, Runner } from '@superdurable/connectors-sdk/pollingtrigger';
9
+ import { z } from 'zod';
10
+
11
+ /** Send one Twilio message behind a durable single-dispatch fence. */
12
+ declare class SendMessageOperation implements Mutation<SendMessageInput, Message> {
13
+ private readonly client;
14
+ /** Bind one client. */ constructor(client: TwilioClient);
15
+ /** Stable manifest definition. */ definition(): _superdurable_connectors_sdk.MutationDefinition;
16
+ /** Receipt identity only; Twilio does not accept an idempotency header. */ idempotencyKey(callId: string): string;
17
+ /** Classify one fenced provider attempt. */
18
+ invoke(call: Call, input: SendMessageInput): Promise<MutationAttempt<Message>>;
19
+ }
20
+ /** Read one Twilio message status. */
21
+ declare class GetMessageOperation implements Query<GetMessageInput, Message> {
22
+ private readonly client;
23
+ /** Bind one client. */ constructor(client: TwilioClient);
24
+ /** Stable manifest definition. */ definition(): _superdurable_connectors_sdk.QueryDefinition;
25
+ /** Classify one provider read. */
26
+ invoke(call: Call, input: GetMessageInput): Promise<QueryAttempt<Message>>;
27
+ }
28
+
29
+ /** Testable Twilio HTTP sender. */
30
+ type TwilioRequestSender = (request: ProviderRequest) => Promise<ProviderResponse>;
31
+ /** Constructor dependencies. */
32
+ interface TwilioClientOptions {
33
+ /** Provider transport. */ send?: TwilioRequestSender;
34
+ /** Receipt clock. */ now?: () => Date;
35
+ }
36
+ /** Complete response or a classified transport failure. */
37
+ type TwilioExchange = {
38
+ response: ProviderResponse;
39
+ isTooLarge: boolean;
40
+ isBodyReadFailed: boolean;
41
+ } | {
42
+ error: Error;
43
+ isProvablyNotSent: boolean;
44
+ };
45
+ /** Validated sender address or Messaging Service. */
46
+ interface MessageSender {
47
+ fromAddress: string;
48
+ messagingServiceSid: string;
49
+ }
50
+ /** Basic authentication material kept outside Dex state. */
51
+ interface TwilioAuthorization {
52
+ username: string;
53
+ password: string;
54
+ }
55
+ /** Credential lookup outcome without secret-bearing errors. */
56
+ type AuthorizationResult = {
57
+ authorization: TwilioAuthorization;
58
+ } | {
59
+ failure: Failure;
60
+ isTransient: boolean;
61
+ };
62
+ /** Authenticated Twilio Messages API client. */
63
+ declare class TwilioClient {
64
+ /** Account SID used in the Messages path. */ readonly accountSid: string;
65
+ /** Fully qualified Messages collection URL. */ readonly messagesURL: string;
66
+ /** Optional default sender. */ readonly defaultSender: MessageSender;
67
+ /** Maximum successful response size. */ readonly maxResponseBytes: number;
68
+ /** Delay between messageReceived polls in milliseconds: pollIntervalMs, 30000 when omitted or zero, at least 5000. */ readonly pollIntervalMs: number;
69
+ private readonly credentials;
70
+ private readonly send;
71
+ private readonly now;
72
+ private readonly addressPolicy;
73
+ /** Validate config and retain provider dependencies. */
74
+ constructor(config: Config, credentials: CredentialProvider<Credentials>, options?: TwilioClientOptions);
75
+ /** Bind the non-idempotent send mutation. */ sendMessage(): SendMessageOperation;
76
+ /** Bind the message status query. */ getMessage(): GetMessageOperation;
77
+ /** Resolve current credentials without leaking lookup errors. */
78
+ authorization(call: Call, operation: string): Promise<AuthorizationResult>;
79
+ /** Ask the credential host for a newer credential after a rejected send. */
80
+ authorizationAfterRejection(call: Call): Promise<AuthorizationResult>;
81
+ private validateAuthorization;
82
+ /** Send one request; only successful responses use the configured body limit. */
83
+ exchange(call: Call, authorization: TwilioAuthorization, method: string, url: string, form?: URLSearchParams, signal?: AbortSignal): Promise<TwilioExchange>;
84
+ /** Decode a safe Twilio Message subset. */
85
+ decodeMessage(body: Uint8Array, authorization: TwilioAuthorization): Message;
86
+ /**
87
+ * Validate one decoded Message resource of this account and keep its safe view. rawIntegerTokens holds the
88
+ * source text of numeric count fields from parseTwilioJSON. Throws TypeError for another account, a
89
+ * malformed field, or a field that reflects the credential.
90
+ */
91
+ convertMessageResource(value: unknown, rawIntegerTokens: WeakMap<object, Map<string, string>>, authorization: TwilioAuthorization): Message;
92
+ /** Make a safe receipt with exact provider IDs. */
93
+ receipt(call: Call, response?: ProviderResponse, objectId?: string, errorCode?: number): ReceiptDraft;
94
+ /** Current receipt time for Retry-After. */ currentTime(): Date;
95
+ }
96
+ /** Whether a value is an E.164 phone number such as +14155550100. */
97
+ declare function isE164PhoneNumber(value: string): boolean;
98
+
99
+ /** Bind a validated Twilio client to a static connection. */
100
+ declare function newConnection(client: TwilioClient, name: string): Connection;
101
+ /** Build a Twilio client from one project connection and its private credentials. */
102
+ declare function newProjectConnection(project: LoadedProject, connectionName: string, options?: TwilioClientOptions): Connection;
103
+
104
+ /** Configuration for the sendMessage connector Step. */
105
+ interface SendMessageStepConfig<StepInput, OperationInput = SendMessageInput, OperationOutput = Message> extends Omit<MutationStepConfig<StepInput, OperationInput, OperationOutput>, 'operation' | 'connection' | 'branches'> {
106
+ /** Named connection supplying this operation. */
107
+ connection: Connection<{
108
+ sendMessage(): Mutation<OperationInput, OperationOutput>;
109
+ }>;
110
+ /** Name matching the bound connection. */
111
+ connectionName: string;
112
+ /** Twilio created the message and returned its SID; delivery status arrives later through getMessage. */
113
+ accepted: StepTarget<MutationResult<OperationOutput>>;
114
+ /** Twilio conclusively rejected the message, such as an invalid To number, an unverified trial recipient, an unsubscribed recipient, or an unusable sender; nothing was sent. */
115
+ providerRejected?: StepTarget<MutationResult<OperationOutput>>;
116
+ /** The request was dispatched but its outcome cannot be confirmed; Twilio has no idempotency key, so the message may exist and must not be resent automatically. */
117
+ uncertain?: StepTarget<MutationResult<OperationOutput>>;
118
+ /** Local input, connection configuration, or connector definition is invalid. */
119
+ defect?: StepTarget<MutationResult<OperationOutput>>;
120
+ }
121
+ /** Build the sendMessage Step from a named connection. */
122
+ declare function newSendMessageStep<StepInput, OperationInput = SendMessageInput, OperationOutput = Message>(configuration: SendMessageStepConfig<StepInput, OperationInput, OperationOutput>): MutationStep<StepInput, OperationInput, OperationOutput>;
123
+ /** Configuration for the getMessage connector Step. */
124
+ interface GetMessageStepConfig<StepInput, OperationInput = GetMessageInput, OperationOutput = Message> extends Omit<QueryStepConfig<StepInput, OperationInput, OperationOutput>, 'operation' | 'connection' | 'branches'> {
125
+ /** Named connection supplying this operation. */
126
+ connection: Connection<{
127
+ getMessage(): Query<OperationInput, OperationOutput>;
128
+ }>;
129
+ /** Name matching the bound connection. */
130
+ connectionName: string;
131
+ /** The message exists and its current status was read. */
132
+ found: StepTarget<QueryResult<OperationOutput>>;
133
+ /** The account has no message with that SID. */
134
+ notFound?: StepTarget<QueryResult<OperationOutput>>;
135
+ /** Twilio conclusively rejected the message query. */
136
+ providerRejected?: StepTarget<QueryResult<OperationOutput>>;
137
+ /** Twilio returned an invalid or oversized message response. */
138
+ invalidResponse?: StepTarget<QueryResult<OperationOutput>>;
139
+ /** Local input, connection configuration, or connector definition is invalid. */
140
+ defect?: StepTarget<QueryResult<OperationOutput>>;
141
+ }
142
+ /** Build the getMessage Step from a named connection. */
143
+ declare function newGetMessageStep<StepInput, OperationInput = GetMessageInput, OperationOutput = Message>(configuration: GetMessageStepConfig<StepInput, OperationInput, OperationOutput>): QueryStep<StepInput, OperationInput, OperationOutput>;
144
+
145
+ /** Branch IDs for sendMessage. */
146
+ declare const SendMessageBranch: {
147
+ readonly Accepted: "accepted";
148
+ readonly ProviderRejected: "providerRejected";
149
+ readonly Uncertain: "uncertain";
150
+ readonly Defect: "defect";
151
+ };
152
+ /** Manifest definition for sendMessage. */
153
+ declare const SendMessageDefinition: MutationDefinition;
154
+ /** Branch IDs for getMessage. */
155
+ declare const GetMessageBranch: {
156
+ readonly Found: "found";
157
+ readonly NotFound: "notFound";
158
+ readonly ProviderRejected: "providerRejected";
159
+ readonly InvalidResponse: "invalidResponse";
160
+ readonly Defect: "defect";
161
+ };
162
+ /** Manifest definition for getMessage. */
163
+ declare const GetMessageDefinition: QueryDefinition;
164
+
165
+ /** Twilio's direction value for a message the account received. */
166
+ declare const InboundMessageDirection = "inbound";
167
+ /** Twilio received an inbound message and is still processing it, such as fetching MMS media. */
168
+ declare const MessageStatusReceiving = "receiving";
169
+ /** Twilio finished processing an inbound message. */
170
+ declare const MessageStatusReceived = "received";
171
+ /** Receiving address UI unit, which saves to. */ declare const UIUnitReceivingAddressInput = "receivingAddressInput";
172
+ /** Receiving address output port. */ declare const UIReceivingAddressInputPortTo = "to";
173
+ /**
174
+ * The messageReceived binding configuration the receivingAddressInput unit saves in Dex Web. to is the
175
+ * receiving Twilio number in E.164 form, such as +14155550100, or a WhatsApp sender written
176
+ * whatsapp:+14155550100; blank receives every inbound message of the connection's account. Changing it for a
177
+ * binding that already polled makes its next poll record a new baseline.
178
+ */
179
+ declare const MessageReceivedTriggerConfigurationSchema: z.ZodObject<{
180
+ to: z.ZodOptional<z.ZodString>;
181
+ }, z.core.$strict>;
182
+ /** The receiving address one messageReceived binding watches. */
183
+ type MessageReceivedTriggerConfiguration = z.infer<typeof MessageReceivedTriggerConfigurationSchema>;
184
+ /**
185
+ * One inbound message read from the Twilio Messages list; field names match the Go connector. Unlike
186
+ * operation results, it carries the message text, because acting on an inbound message needs it. Media URLs,
187
+ * Twilio error text, and credentials are never included. The Trigger event ID is "twilio-message-" followed by
188
+ * the message SID.
189
+ */
190
+ declare const MessageReceivedEventSchema: z.ZodObject<{
191
+ message: z.ZodObject<{
192
+ sid: z.ZodOptional<z.ZodString>;
193
+ accountSid: z.ZodString;
194
+ messagingServiceSid: z.ZodOptional<z.ZodString>;
195
+ from: z.ZodOptional<z.ZodString>;
196
+ to: z.ZodString;
197
+ status: z.ZodOptional<z.ZodString>;
198
+ direction: z.ZodOptional<z.ZodString>;
199
+ errorCode: z.ZodOptional<z.ZodNumber>;
200
+ segmentCount: z.ZodOptional<z.ZodNumber>;
201
+ mediaCount: z.ZodOptional<z.ZodNumber>;
202
+ price: z.ZodOptional<z.ZodString>;
203
+ priceUnit: z.ZodOptional<z.ZodString>;
204
+ createdAt: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
205
+ sentAt: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
206
+ updatedAt: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
207
+ }, z.core.$strict>;
208
+ body: z.ZodOptional<z.ZodString>;
209
+ }, z.core.$strict>;
210
+ /** One inbound message. */
211
+ type MessageReceivedEvent = z.infer<typeof MessageReceivedEventSchema>;
212
+ /** Manifest definition of messageReceived. */
213
+ declare const MessageReceivedTriggerDefinition: TriggerDefinition;
214
+ /** One static application binding of messageReceived. */
215
+ interface MessageReceivedTriggerBindingConfig {
216
+ /** Static connection name. */ connectionName: string;
217
+ /** Static binding name. */ bindingName: string;
218
+ /** Connector Studio configuration units for the binding, such as the receivingAddressInput unit. */ configurationUI: ConnectorConfigurationUI;
219
+ }
220
+ /** Declare a static messageReceived binding for Flow Definition tooling and Dex Web. */
221
+ declare function defineMessageReceivedTriggerBinding(config: MessageReceivedTriggerBindingConfig): TriggerBindingDefinition;
222
+ /** Decode a replayed message, including one a Go replica recorded. */
223
+ declare function decodeMessageReceivedPayload(_payloadJSON: string, payloadBytes: Uint8Array): MessageReceivedEvent;
224
+ /** Binds one messageReceived configuration to its application target and cursor. */
225
+ interface MessageReceivedTriggerRoute {
226
+ /** The stable application binding name, unique within the runner. */ bindingName: string;
227
+ /** Selects the receiving address; blank receives every inbound message of the account. */ configuration: MessageReceivedTriggerConfiguration;
228
+ /**
229
+ * Routes each inbound message into the application. A target from newDurableTriggerTarget records each
230
+ * message before the cursor commits past it; any other target consumes it first.
231
+ */
232
+ target: TriggerTarget<MessageReceivedEvent>;
233
+ /**
234
+ * Stores the binding's DateSent watermark and delivered-message snapshot, such as LoadedProject.pollCursorStore.
235
+ * Omitted keeps it in memory, so every process start records a new baseline and messages received while
236
+ * stopped are lost.
237
+ */
238
+ cursor?: CursorStore | undefined;
239
+ }
240
+ /**
241
+ * Create one poll runner for the messageReceived bindings polled through one connection. run replays each
242
+ * durable target, records a baseline for a binding without a cursor, then lists each binding's Messages each
243
+ * pollInterval with jitter. A cursor for another account or receiving address records a new baseline and logs
244
+ * a WARN record; messages received between the last poll and the new baseline are not delivered. A 429 pauses
245
+ * every binding of the connection for Retry-After, or backs off exponentially without it; other failures back
246
+ * off per binding up to 15 minutes. Delivery is at least once, and each message keeps one Trigger event ID,
247
+ * from its SID, across refetches. logger receives records with binding identity, never message bodies,
248
+ * addresses, or credentials. Throws for no routes, a blank or repeated binding name, a missing target, an
249
+ * invalid configuration, or a mock connection.
250
+ */
251
+ declare function newMessageTriggerRunner(connection: Connection, routes: MessageReceivedTriggerRoute[], logger?: TriggerLogger): Runner;
252
+ /** Selects one messageReceived binding saved in the project configuration. */
253
+ interface ProjectMessageReceivedTriggerRoute {
254
+ /** The saved binding's name. */ bindingName: string;
255
+ /** Routes each inbound message into the application, usually newDexFlowTriggerTarget. */ target: TriggerTarget<MessageReceivedEvent>;
256
+ }
257
+ /**
258
+ * Create a durable runner for messageReceived bindings saved in the loaded project. connection is the
259
+ * project's connection from newProjectConnection; the caller shares it with the Flow. Each binding's saved
260
+ * receiving address is loaded (an unsaved binding receives every inbound message of the account), and each
261
+ * route records messages in its binding's project Trigger inbox before its watermark commits in the binding's
262
+ * project poll cursor, so a restarted or replaced replica neither misses nor repeats a message. logger also
263
+ * receives the inboxes' records. Throws for an invalid saved configuration or route, as newMessageTriggerRunner does.
264
+ */
265
+ declare function newProjectMessageTriggerRunner(project: LoadedProject, connection: Connection, routes: ProjectMessageReceivedTriggerRoute[], logger?: TriggerLogger): Runner;
266
+ /** Configuration of one messageReceived Trigger with an in-memory cursor. */
267
+ interface MessageReceivedTriggerConfig {
268
+ /** Twilio connection from newProjectConnection or newConnection. */ connection: Connection;
269
+ /** Static connection name; must equal the connection's name. */ connectionName: string;
270
+ /** Static binding name. */ bindingName: string;
271
+ /** The receiving address; blank receives every inbound message. */ configuration: MessageReceivedTriggerConfiguration;
272
+ /** Routes accepted events into the application. */ target: TriggerTarget<MessageReceivedEvent>;
273
+ /** Receives the runner's records; omitted uses defaultTriggerLogger. */ logger?: TriggerLogger | undefined;
274
+ }
275
+ /**
276
+ * Create one messageReceived binding's TriggerRunner, as Go's generated NewMessageReceivedTrigger does. It has
277
+ * no project storage, so it keeps the cursor in memory and records a new baseline on every start; use
278
+ * newProjectMessageTriggerRunner for a durable cursor and inbox. Throws for a mismatched connection name, an
279
+ * invalid configuration, or a mock connection.
280
+ */
281
+ declare function newMessageReceivedTrigger(config: MessageReceivedTriggerConfig): TriggerRunner;
282
+
283
+ export { Config, Connection, Credentials, GetMessageBranch, GetMessageDefinition, GetMessageInput, GetMessageOperation, InboundMessageDirection, Message, type MessageReceivedEvent, MessageReceivedEventSchema, type MessageReceivedTriggerBindingConfig, type MessageReceivedTriggerConfig, type MessageReceivedTriggerConfiguration, MessageReceivedTriggerConfigurationSchema, MessageReceivedTriggerDefinition, type MessageReceivedTriggerRoute, MessageStatusReceived, MessageStatusReceiving, type ProjectMessageReceivedTriggerRoute, SendMessageBranch, SendMessageDefinition, SendMessageInput, SendMessageOperation, TwilioClient, type TwilioClientOptions, type TwilioRequestSender, UIReceivingAddressInputPortTo, UIUnitReceivingAddressInput, decodeMessageReceivedPayload, defineMessageReceivedTriggerBinding, isE164PhoneNumber, newConnection, newGetMessageStep, newMessageReceivedTrigger, newMessageTriggerRunner, newProjectConnection, newProjectMessageTriggerRunner, newSendMessageStep };