glitchgrab 1.63.1 → 1.65.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.
package/dist/server.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { n as ReportType, m as ReportSeverity, l as ReportResult } from './types-Dp5Sh_hd.mjs';
1
+ import { n as ReportType, m as ReportSeverity, l as ReportResult } from './types-Dw587jLi.mjs';
2
2
  import 'react';
3
3
 
4
4
  /** Who to attribute the report to. A server has no signed-in user, so this is the job or service. */
@@ -322,7 +322,8 @@ type DeleteCallResult = {
322
322
  };
323
323
  /**
324
324
  * Calls shared with the client on the key's project, newest first. No links —
325
- * open one with {@link getCall}.
325
+ * open one with {@link getCall}. Every {@link placeCall} call is shared from
326
+ * the start, firm lines (`ownerId`) included.
326
327
  *
327
328
  * ```ts
328
329
  * // app/admin/calls/page.tsx — server component
@@ -342,6 +343,11 @@ declare function listCalls(options?: ListCallsOptions): Promise<CallListItem[]>;
342
343
  * Links expire after `linksExpireInSeconds` — read the call when the page
343
344
  * renders and never store them.
344
345
  *
346
+ * A {@link placeCall} call is shared from the start, so `getCall(callId)` with
347
+ * the `callId` from `placeCall` or any `call.*` webhook plays its recording —
348
+ * firm lines (`ownerId`) included (#723). `call.recording_ready` carries no
349
+ * link on purpose: fetch a fresh one here when someone presses play.
350
+ *
345
351
  * Returns `null` when the call does not exist, is not shared, and on any
346
352
  * failure — call `notFound()` on it. Never throws.
347
353
  */
@@ -863,18 +869,28 @@ type OperatorRingNumbersResult = {
863
869
  error: string;
864
870
  code?: string;
865
871
  };
872
+ /**
873
+ * Options for calls about one person on a line. `ownerId` = that customer's own
874
+ * line (#723 — one line per PracticeStacks firm, the same id you pass to
875
+ * {@link addLineCaller}): the person must sit on it, and test rings come from
876
+ * its number. Omitted = any of the project's lines.
877
+ */
878
+ interface LineCallsOptions extends CallsOptions {
879
+ ownerId?: string;
880
+ }
866
881
  /**
867
882
  * The phones Glitchgrab can ring for one person on the project's phone line —
868
883
  * for a "Ring me on: [Default ▾]" picker beside your Call button. Verified
869
884
  * numbers only. `numbers: []` = dial will refuse with `NO_VERIFIED_NUMBER`;
870
- * not on the line = `{ ok: false, code: "NOT_ON_LINE" }`. Never throws.
885
+ * not on the line = `{ ok: false, code: "NOT_ON_LINE" }`. Pass `{ ownerId }`
886
+ * for someone on a customer's line. Never throws.
871
887
  *
872
888
  * ```ts
873
889
  * const r = await getOperatorRingNumbers({ email: admin.email }); // GLITCHGRAB_CALLS_KEY=ggc_…
874
890
  * if (r.ok) render(r.numbers); // pass the chosen phone to dialFollowUp(…, { ringPhone })
875
891
  * ```
876
892
  */
877
- declare function getOperatorRingNumbers(operator: FollowUpOperator, options?: CallsOptions): Promise<OperatorRingNumbersResult>;
893
+ declare function getOperatorRingNumbers(operator: FollowUpOperator, options?: LineCallsOptions): Promise<OperatorRingNumbersResult>;
878
894
  type LineCallerResult = {
879
895
  ok: true;
880
896
  created: boolean;
@@ -898,6 +914,9 @@ type LineCallerResult = {
898
914
  * `CALLERS_OFF` (the line's owner switched it off), `CALLER_CAP` (10 per line).
899
915
  * Never throws.
900
916
  *
917
+ * `ownerId` = seat them on that customer's own line (#716 — one line per
918
+ * PracticeStacks firm). Omitted = the project's line.
919
+ *
901
920
  * ```ts
902
921
  * const r = await addLineCaller({ email: admin.email, name: admin.name });
903
922
  * if (r.ok) openMyPhones(r.numbers);
@@ -907,13 +926,255 @@ declare function addLineCaller(caller: {
907
926
  email: string;
908
927
  name: string;
909
928
  phone?: string;
929
+ ownerId?: string;
910
930
  }, options?: CallsOptions): Promise<LineCallerResult>;
931
+ /** Fields every `call.*` webhook carries (#716). `refKey`/`ownerId` are null when not set. */
932
+ interface CallWebhookBase {
933
+ callId: string;
934
+ repoId: string | null;
935
+ lineId: string | null;
936
+ direction: "outbound" | "inbound" | null;
937
+ /** The other party, E.164. */
938
+ peer: string | null;
939
+ /** What you passed to {@link placeCall}. */
940
+ refKey: string | null;
941
+ /** The customer whose line carried the call. */
942
+ ownerId: string | null;
943
+ }
944
+ /**
945
+ * The body Glitchgrab POSTs to your webhook for a phone call, signed with
946
+ * `X-Glitchgrab-Signature: sha256=<hex HMAC of the raw body>`. Narrow on `event`.
947
+ */
948
+ type CallWebhook = {
949
+ event: "call.started";
950
+ timestamp: string;
951
+ data: CallWebhookBase & {
952
+ ringing: string;
953
+ };
954
+ } | {
955
+ event: "call.answered";
956
+ timestamp: string;
957
+ data: CallWebhookBase & {
958
+ answeredAt: string;
959
+ };
960
+ } | {
961
+ event: "call.completed";
962
+ timestamp: string;
963
+ data: CallWebhookBase & {
964
+ /** RECORDED = they talked; NO_ANSWER (+ missedBy); FAILED. */
965
+ status: string;
966
+ missedBy: "operator" | "customer" | null;
967
+ durationSec: number | null;
968
+ hangupCause: string | null;
969
+ };
970
+ } | {
971
+ event: "call.recording_ready";
972
+ timestamp: string;
973
+ data: Omit<CallWebhookBase, "lineId"> & {
974
+ durationSec: number | null;
975
+ };
976
+ } | {
977
+ event: "call.summary_ready";
978
+ timestamp: string;
979
+ data: Pick<CallWebhookBase, "callId" | "repoId" | "refKey" | "ownerId"> & {
980
+ /** "phone", "bot" or "extension". */
981
+ recorder: string;
982
+ title: string | null;
983
+ summary: string | null;
984
+ };
985
+ };
986
+ /** `phone.*` webhooks for a customer's automatic line (#716). Same signing as {@link CallWebhook}. */
987
+ type PhoneLineWebhook = {
988
+ event: "phone.kyc_status";
989
+ timestamp: string;
990
+ data: {
991
+ ownerId: string;
992
+ status: string;
993
+ reason: string | null;
994
+ };
995
+ } | {
996
+ event: "phone.line_ready";
997
+ timestamp: string;
998
+ data: {
999
+ ownerId: string;
1000
+ number: string;
1001
+ lineId: string;
1002
+ };
1003
+ };
1004
+ type PlaceCallResult = {
1005
+ ok: true;
1006
+ callId: string;
1007
+ ringing: string;
1008
+ ringNumbers: string[];
1009
+ from: string;
1010
+ } | {
1011
+ ok: false;
1012
+ error: string;
1013
+ code?: string;
1014
+ };
1015
+ /**
1016
+ * Start a recorded call from your own screen (#716) — Glitchgrab rings
1017
+ * `operator`'s verified phone from the line, then bridges to `to`. No
1018
+ * follow-up is created; use {@link dialFollowUp} for that.
1019
+ *
1020
+ * `ownerId` = call from that customer's own line (one line per PracticeStacks
1021
+ * firm); the operator must be seated on it ({@link addLineCaller} with the
1022
+ * same `ownerId`). `refKey` = your own key for what the call is about — every
1023
+ * `call.*` webhook (`call.started`, `call.answered`, `call.completed`,
1024
+ * `call.recording_ready`, `call.summary_ready`) carries it back with `ownerId`.
1025
+ * The recording plays through {@link getCall}(`callId`).
1026
+ * Check your own permissions before calling this. Refusals carry `code`:
1027
+ * `NOT_ON_LINE`, `NO_VERIFIED_NUMBER`, `RING_PHONE_NOT_YOURS`. Never throws.
1028
+ *
1029
+ * ```ts
1030
+ * const r = await placeCall({
1031
+ * operator: { email: staff.email },
1032
+ * to: client.phone,
1033
+ * ownerId: firm.id,
1034
+ * refKey: client.id,
1035
+ * }); // GLITCHGRAB_CALLS_KEY=ggc_…
1036
+ * ```
1037
+ */
1038
+ declare function placeCall(call: {
1039
+ operator: FollowUpOperator;
1040
+ to: string;
1041
+ ownerId?: string;
1042
+ refKey?: string;
1043
+ title?: string;
1044
+ ringPhone?: string;
1045
+ }, options?: CallsOptions): Promise<PlaceCallResult>;
1046
+ interface PhoneLineInfo {
1047
+ number: string;
1048
+ label: string | null;
1049
+ active: boolean;
1050
+ /** People seated on it; anyone else gets `NOT_ON_LINE`. */
1051
+ callers: number;
1052
+ }
1053
+ /** Where a customer's automatic line is up to (#716). */
1054
+ interface PhoneLineRequest {
1055
+ /** Plivo's KYC status: submitted | accepted | rejected | suspended | expired. */
1056
+ kycStatus: string;
1057
+ /** Why Plivo rejected it — show it to the firm so they can fix and resubmit. */
1058
+ kycReason: string | null;
1059
+ /** The firm agreed to the monthly charge ({@link enableCalling}). */
1060
+ enabled: boolean;
1061
+ /** NONE | BUYING | BOUGHT | FAILED (retried automatically). */
1062
+ buyState: string;
1063
+ buyError: string | null;
1064
+ number: string | null;
1065
+ }
1066
+ interface PhoneLineStatus {
1067
+ line: PhoneLineInfo | null;
1068
+ /** Null when no KYC was submitted for this customer. */
1069
+ request: PhoneLineRequest | null;
1070
+ }
1071
+ /**
1072
+ * A customer's phone line and, when you submitted their KYC, how far the
1073
+ * automatic purchase has got (#716) — for the firm's "Calling" settings:
1074
+ * no request → "Submit KYC"; `kycStatus: "rejected"` → show `kycReason`;
1075
+ * accepted but `enabled: false` → "Turn on calling (₹… /month)"; `line` set →
1076
+ * ready. `ownerId` omitted = the project's own line. `null` only on failure
1077
+ * (no key, network). Never throws.
1078
+ */
1079
+ declare function getPhoneLine(params?: {
1080
+ ownerId?: string;
1081
+ }, options?: CallsOptions): Promise<PhoneLineStatus | null>;
1082
+ type LineRequestResult = {
1083
+ ok: true;
1084
+ request: PhoneLineRequest;
1085
+ } | {
1086
+ ok: false;
1087
+ error: string;
1088
+ code?: string;
1089
+ };
1090
+ /**
1091
+ * Submit a customer's KYC so they get their own phone number (#716). Plivo
1092
+ * reviews it (usually minutes, sometimes a day); the `phone.kyc_status`
1093
+ * webhook says when. Rejected → fix and call again. Certificates: PDF, JPG or
1094
+ * PNG, under 4 MB together; they go straight to Plivo, Glitchgrab keeps no
1095
+ * copy. Refusals carry `code`: `KYC_PENDING`, `KYC_DONE`, `BAD_FILE`,
1096
+ * `PROVIDER`. Nothing is bought until {@link enableCalling}. Never throws.
1097
+ */
1098
+ declare function submitPhoneKyc(kyc: {
1099
+ ownerId: string;
1100
+ /** Legal name, as on the certificates. */
1101
+ businessName: string;
1102
+ email: string;
1103
+ addressLine1: string;
1104
+ city: string;
1105
+ state: string;
1106
+ /** 6-digit PIN code. */
1107
+ postalCode: string;
1108
+ registrationCertificate: Blob;
1109
+ gstCertificate: Blob;
1110
+ }, options?: CallsOptions): Promise<LineRequestResult>;
1111
+ /**
1112
+ * The firm turned calling on and agreed to the monthly charge for its own
1113
+ * number (#716). `agreedBy` (who agreed) and the time are kept as the billing
1114
+ * record. Once the KYC is accepted — now or later — Glitchgrab rents the
1115
+ * number and creates the line (`phone.line_ready` webhook); then seat staff
1116
+ * with {@link addLineCaller} and the same `ownerId`. `areaCode` = STD code to
1117
+ * search under ("20" Pune), else any free Indian number. Never throws.
1118
+ */
1119
+ declare function enableCalling(params: {
1120
+ ownerId: string;
1121
+ agreedBy: string;
1122
+ areaCode?: string;
1123
+ }, options?: CallsOptions): Promise<LineRequestResult>;
1124
+ /**
1125
+ * The firm turned calling off (#716): its line stops ringing and calling at
1126
+ * once, consent is cleared, and Navibyte is told to release the number.
1127
+ * {@link enableCalling} again switches the same line back on. Never throws.
1128
+ */
1129
+ declare function disableCalling(params: {
1130
+ ownerId: string;
1131
+ }, options?: CallsOptions): Promise<LineRequestResult>;
1132
+ interface RegisteredWebhook {
1133
+ id: string;
1134
+ url: string;
1135
+ events: string[];
1136
+ }
1137
+ /**
1138
+ * Register your backend's webhook from code (#716) — scoped to this project,
1139
+ * no Settings clicks. https and a public host only. The `secret` comes back
1140
+ * once: verify every delivery's `X-Glitchgrab-Signature` (`sha256=` HMAC of the
1141
+ * raw body) with it. Same URL twice → refused; remove it first to rotate.
1142
+ * Never throws.
1143
+ */
1144
+ declare function registerWebhook(webhook: {
1145
+ url: string;
1146
+ events: string[];
1147
+ }, options?: CallsOptions): Promise<{
1148
+ ok: true;
1149
+ webhook: RegisteredWebhook;
1150
+ secret: string;
1151
+ } | {
1152
+ ok: false;
1153
+ error: string;
1154
+ }>;
1155
+ /** This project's webhooks, without secrets. `[]` on any failure. Never throws. */
1156
+ declare function listWebhooks(options?: CallsOptions): Promise<RegisteredWebhook[]>;
1157
+ /** Remove one of this project's webhooks. Never throws. */
1158
+ declare function removeWebhook(id: string, options?: CallsOptions): Promise<{
1159
+ ok: true;
1160
+ } | {
1161
+ ok: false;
1162
+ error: string;
1163
+ }>;
911
1164
  /**
912
1165
  * Take a caller your key added off the line, with the phones kept for them —
913
1166
  * e.g. when they leave your admin team. Someone the line's owner added →
914
- * `code: "NOT_KEY_CALLER"`. Never throws.
1167
+ * `code: "NOT_KEY_CALLER"`; not on it → `code: "NOT_ON_LINE"`. Never throws.
1168
+ *
1169
+ * `{ ownerId }` = only their seat on that customer's line (#723): staff of two
1170
+ * firms keep the other one, and access + phones go with their last seat.
1171
+ * Omitted = off every line of the project.
1172
+ *
1173
+ * ```ts
1174
+ * await removeLineCaller(staff.email, { ownerId: firm.id });
1175
+ * ```
915
1176
  */
916
- declare function removeLineCaller(email: string, options?: CallsOptions): Promise<RingNumberWriteResult>;
1177
+ declare function removeLineCaller(email: string, options?: LineCallsOptions): Promise<RingNumberWriteResult>;
917
1178
  /** One saved ring number, verified or not — the management view (#654). */
918
1179
  interface RingNumber {
919
1180
  id: string;
@@ -948,34 +1209,38 @@ type RingNumberWriteResult<T = object> = ({
948
1209
  * — for your "manage my phones" screen. Ring numbers are managed only from
949
1210
  * your product; Glitchgrab shows them read-only. A refusal carries `code`
950
1211
  * (`NOT_ON_LINE`), so "not on the line" reads differently from "network down".
951
- * Never throws.
1212
+ * `{ ownerId }` for someone on a customer's line. Never throws.
952
1213
  */
953
- declare function listRingNumbers(operator: FollowUpOperator, options?: CallsOptions): Promise<RingNumberWriteResult<RingNumberList>>;
1214
+ declare function listRingNumbers(operator: FollowUpOperator, options?: LineCallsOptions): Promise<RingNumberWriteResult<RingNumberList>>;
954
1215
  /**
955
1216
  * Save a phone for `operator` and place its test ring at once: the project's
956
1217
  * line calls it and whoever holds it presses 1. Never rung for a call until
957
1218
  * then; the line's owner is alerted when it is verified. Max 5 per person.
958
1219
  * `testRing: "failed"` = saved but not rung — retry with {@link testRingNumber}.
1220
+ * `{ ownerId }` = they sit on that customer's line, and its number test-rings.
959
1221
  */
960
1222
  declare function addRingNumber(operator: FollowUpOperator, number: {
961
1223
  phone: string;
962
1224
  label?: string;
963
- }, options?: CallsOptions): Promise<RingNumberWriteResult<{
1225
+ }, options?: LineCallsOptions): Promise<RingNumberWriteResult<{
964
1226
  id: string;
965
1227
  testRing: "ringing" | "failed";
966
1228
  verifyError: string | null;
967
1229
  }>>;
968
- /** Rename, make Default (verified only) or move one place up/down. Never throws. */
1230
+ /** Rename, make Default (verified only) or move one place up/down. `{ ownerId }` as in {@link LineCallsOptions}. Never throws. */
969
1231
  declare function updateRingNumber(id: string, change: {
970
1232
  label?: string | null;
971
1233
  makeDefault?: true;
972
1234
  move?: "up" | "down";
973
- }, options?: CallsOptions): Promise<RingNumberWriteResult>;
974
- /** Remove one; the next verified number becomes Default. Never throws. */
975
- declare function removeRingNumber(id: string, options?: CallsOptions): Promise<RingNumberWriteResult>;
976
- /** Place the test ring again (6 per person, 30 per project an hour). Never throws. */
977
- declare function testRingNumber(id: string, options?: CallsOptions): Promise<RingNumberWriteResult<{
1235
+ }, options?: LineCallsOptions): Promise<RingNumberWriteResult>;
1236
+ /** Remove one; the next verified number becomes Default. `{ ownerId }` as in {@link LineCallsOptions}. Never throws. */
1237
+ declare function removeRingNumber(id: string, options?: LineCallsOptions): Promise<RingNumberWriteResult>;
1238
+ /**
1239
+ * Place the test ring again (6 per person, 30 per project an hour). `{ ownerId }`
1240
+ * = rings from that customer's line, e.g. retrying a firm caller's failed ring. Never throws.
1241
+ */
1242
+ declare function testRingNumber(id: string, options?: LineCallsOptions): Promise<RingNumberWriteResult<{
978
1243
  verified: boolean;
979
1244
  }>>;
980
1245
 
981
- export { type Booking, type BookingAnswer, type BookingClientNotice, type BookingMutationResult, type BookingNotifyRecipient, type BookingQuestion, type BookingQuestionInput, type BookingSettings, type BookingSettingsChanges, type BookingSettingsResult, type BookingSettingsState, type BookingWorkingHours, type Call, type CallAudio, type CallListItem, type CallMoment, type CallParticipant, type CallsOptions, type CaptureServerErrorsOptions, type DeleteCallResult, type FollowUp, type FollowUpBooking, type FollowUpCall, type FollowUpDetail, type FollowUpDue, type FollowUpNote, type FollowUpOperator, type FollowUpWriteResult, type GetCallOptions, type Guide, type GuideReadOptions, type GuideSummary, type Lead, type LineCallerResult, type ListBookingsOptions, type ListCallsOptions, type ListLeadsOptions, type OperatorRingNumber, type OperatorRingNumbersResult, ReportResult, ReportSeverity, ReportType, type RingErrorCode, type RingNumber, type RingNumberList, type RingNumberWriteResult, type ServerReportOptions, type ServerReporterConfig, type ServerReporterIdentity, type SignSessionOptions, addFollowUpNote, addLineCaller, addRingNumber, cancelBooking, captureServerErrors, configureServerReporter, deleteCall, dialFollowUp, discardBookingQuestionsDraft, editFollowUpNote, escapeJsonForScript, getBookingSettings, getCall, getFollowUp, getGuide, getOperatorRingNumbers, listBookings, listCalls, listFollowUps, listGuides, listLeads, listRingNumbers, publishBookingQuestions, removeLineCaller, removeRingNumber, reportServerError, rescheduleBooking, resetServerReporter, setFollowUpBooking, signSession, testRingNumber, updateBookingSettings, updateRingNumber };
1246
+ export { type Booking, type BookingAnswer, type BookingClientNotice, type BookingMutationResult, type BookingNotifyRecipient, type BookingQuestion, type BookingQuestionInput, type BookingSettings, type BookingSettingsChanges, type BookingSettingsResult, type BookingSettingsState, type BookingWorkingHours, type Call, type CallAudio, type CallListItem, type CallMoment, type CallParticipant, type CallWebhook, type CallsOptions, type CaptureServerErrorsOptions, type DeleteCallResult, type FollowUp, type FollowUpBooking, type FollowUpCall, type FollowUpDetail, type FollowUpDue, type FollowUpNote, type FollowUpOperator, type FollowUpWriteResult, type GetCallOptions, type Guide, type GuideReadOptions, type GuideSummary, type Lead, type LineCallerResult, type LineCallsOptions, type LineRequestResult, type ListBookingsOptions, type ListCallsOptions, type ListLeadsOptions, type OperatorRingNumber, type OperatorRingNumbersResult, type PhoneLineInfo, type PhoneLineRequest, type PhoneLineStatus, type PhoneLineWebhook, type PlaceCallResult, type RegisteredWebhook, ReportResult, ReportSeverity, ReportType, type RingErrorCode, type RingNumber, type RingNumberList, type RingNumberWriteResult, type ServerReportOptions, type ServerReporterConfig, type ServerReporterIdentity, type SignSessionOptions, addFollowUpNote, addLineCaller, addRingNumber, cancelBooking, captureServerErrors, configureServerReporter, deleteCall, dialFollowUp, disableCalling, discardBookingQuestionsDraft, editFollowUpNote, enableCalling, escapeJsonForScript, getBookingSettings, getCall, getFollowUp, getGuide, getOperatorRingNumbers, getPhoneLine, listBookings, listCalls, listFollowUps, listGuides, listLeads, listRingNumbers, listWebhooks, placeCall, publishBookingQuestions, registerWebhook, removeLineCaller, removeRingNumber, removeWebhook, reportServerError, rescheduleBooking, resetServerReporter, setFollowUpBooking, signSession, submitPhoneKyc, testRingNumber, updateBookingSettings, updateRingNumber };