@linqapp/sdk 0.28.1 → 0.29.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.
Files changed (90) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/client.d.mts +117 -0
  3. package/client.d.mts.map +1 -1
  4. package/client.d.ts +117 -0
  5. package/client.d.ts.map +1 -1
  6. package/client.js +117 -0
  7. package/client.js.map +1 -1
  8. package/client.mjs +117 -0
  9. package/client.mjs.map +1 -1
  10. package/package.json +1 -1
  11. package/resources/attachments.d.mts +7 -1
  12. package/resources/attachments.d.mts.map +1 -1
  13. package/resources/attachments.d.ts +7 -1
  14. package/resources/attachments.d.ts.map +1 -1
  15. package/resources/available-number.d.mts +9 -6
  16. package/resources/available-number.d.mts.map +1 -1
  17. package/resources/available-number.d.ts +9 -6
  18. package/resources/available-number.d.ts.map +1 -1
  19. package/resources/available-number.js +8 -5
  20. package/resources/available-number.js.map +1 -1
  21. package/resources/available-number.mjs +8 -5
  22. package/resources/available-number.mjs.map +1 -1
  23. package/resources/chats/location.d.mts +52 -11
  24. package/resources/chats/location.d.mts.map +1 -1
  25. package/resources/chats/location.d.ts +52 -11
  26. package/resources/chats/location.d.ts.map +1 -1
  27. package/resources/chats/location.js +52 -11
  28. package/resources/chats/location.js.map +1 -1
  29. package/resources/chats/location.mjs +52 -11
  30. package/resources/chats/location.mjs.map +1 -1
  31. package/resources/chats/typing.d.mts +46 -10
  32. package/resources/chats/typing.d.mts.map +1 -1
  33. package/resources/chats/typing.d.ts +46 -10
  34. package/resources/chats/typing.d.ts.map +1 -1
  35. package/resources/chats/typing.js +46 -10
  36. package/resources/chats/typing.js.map +1 -1
  37. package/resources/chats/typing.mjs +46 -10
  38. package/resources/chats/typing.mjs.map +1 -1
  39. package/resources/index.d.mts +1 -0
  40. package/resources/index.d.mts.map +1 -1
  41. package/resources/index.d.ts +1 -0
  42. package/resources/index.d.ts.map +1 -1
  43. package/resources/index.js +3 -1
  44. package/resources/index.js.map +1 -1
  45. package/resources/index.mjs +1 -0
  46. package/resources/index.mjs.map +1 -1
  47. package/resources/messages.d.mts +8 -6
  48. package/resources/messages.d.mts.map +1 -1
  49. package/resources/messages.d.ts +8 -6
  50. package/resources/messages.d.ts.map +1 -1
  51. package/resources/messages.js +6 -4
  52. package/resources/messages.js.map +1 -1
  53. package/resources/messages.mjs +6 -4
  54. package/resources/messages.mjs.map +1 -1
  55. package/resources/payment-requests.d.mts +413 -0
  56. package/resources/payment-requests.d.mts.map +1 -0
  57. package/resources/payment-requests.d.ts +413 -0
  58. package/resources/payment-requests.d.ts.map +1 -0
  59. package/resources/payment-requests.js +203 -0
  60. package/resources/payment-requests.js.map +1 -0
  61. package/resources/payment-requests.mjs +199 -0
  62. package/resources/payment-requests.mjs.map +1 -0
  63. package/resources/phone-numbers.d.mts +5 -43
  64. package/resources/phone-numbers.d.mts.map +1 -1
  65. package/resources/phone-numbers.d.ts +5 -43
  66. package/resources/phone-numbers.d.ts.map +1 -1
  67. package/resources/webhook-events.d.mts +1 -1
  68. package/resources/webhook-events.d.mts.map +1 -1
  69. package/resources/webhook-events.d.ts +1 -1
  70. package/resources/webhook-events.d.ts.map +1 -1
  71. package/resources/webhooks.d.mts +1 -25
  72. package/resources/webhooks.d.mts.map +1 -1
  73. package/resources/webhooks.d.ts +1 -25
  74. package/resources/webhooks.d.ts.map +1 -1
  75. package/src/client.ts +131 -0
  76. package/src/resources/attachments.ts +7 -0
  77. package/src/resources/available-number.ts +9 -6
  78. package/src/resources/chats/location.ts +52 -11
  79. package/src/resources/chats/typing.ts +46 -10
  80. package/src/resources/index.ts +7 -0
  81. package/src/resources/messages.ts +8 -6
  82. package/src/resources/payment-requests.ts +487 -0
  83. package/src/resources/phone-numbers.ts +5 -46
  84. package/src/resources/webhook-events.ts +5 -1
  85. package/src/resources/webhooks.ts +5 -27
  86. package/src/version.ts +1 -1
  87. package/version.d.mts +1 -1
  88. package/version.d.ts +1 -1
  89. package/version.js +1 -1
  90. package/version.mjs +1 -1
@@ -2,23 +2,59 @@ import { APIResource } from "../../core/resource.mjs";
2
2
  import { APIPromise } from "../../core/api-promise.mjs";
3
3
  import { RequestOptions } from "../../internal/request-options.mjs";
4
4
  /**
5
- * Request and retrieve real-time location data via iMessage.
6
- *
7
- * Use these endpoints to request a contact's location, retrieve location data
8
- * for contacts who are sharing with you, and subscribe to webhooks when someone
9
- * starts or stops sharing their location.
5
+ * Request a contact's location, retrieve location for contacts sharing with you,
6
+ * and subscribe to webhooks when someone starts or stops sharing.
10
7
  *
11
8
  * **Coordinates** are returned in [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) format:
12
9
  * `[longitude, latitude]` or `[longitude, latitude, altitude]` if altitude is available.
10
+ *
11
+ * ### Reading location is poll-based
12
+ *
13
+ * Poll `GET /v3/chats/{chatId}/location` whenever you need the latest position.
14
+ * **There is no webhook that pushes updated coordinates** — the
15
+ * `location.sharing.started` / `location.sharing.stopped` webhooks fire only when a
16
+ * contact begins or ends sharing, not on each position update. To track a moving
17
+ * contact, poll the `GET` endpoint.
18
+ *
19
+ * ### Freshness
20
+ *
21
+ * Each feature's `properties.updated_at` tells you when that participant's
22
+ * location was last updated — use it to judge freshness.
23
+ *
24
+ * ### Polling guidance
25
+ *
26
+ * Locations refresh on Apple's cadence, not per request — polling faster than a
27
+ * participant's location actually updates just returns the same position. Poll at a
28
+ * modest interval (for example, once every few minutes per chat) rather than
29
+ * continuously.
30
+ *
31
+ * ### Why is location empty after `location.sharing.started` fired?
32
+ *
33
+ * If the contact started sharing from the **standalone Find My app** instead of the
34
+ * Messages conversation, the share may be tied to their **Apple ID email** rather
35
+ * than their phone number — the webhook's `shared_by` field shows the email in that
36
+ * case. Location is readable only through a chat with the handle that shared, so
37
+ * `GET /v3/chats/{chatId}/location` on the phone-number chat stays empty.
38
+ *
39
+ * The fix: have the contact stop sharing and re-share from **Find My inside the
40
+ * Messages conversation** with your number.
13
41
  */
14
42
  export declare class Location extends APIResource {
15
43
  /**
16
- * Send a location sharing request to a contact. They will receive an iMessage
17
- * prompt asking them to share their location.
44
+ * Request a contact in a chat to share their location. They receive an iMessage
45
+ * prompt and must accept before any location is available; once they do, read
46
+ * their location coordinates with `GET /v3/chats/{chatId}/location`.
18
47
  *
19
- * Location requests only work in **1:1 iMessage chats** (Apple limitation).
20
- * Attempting to request location in a group chat, or in an SMS or RCS chat,
21
- * returns `409` (Operation not supported on this chat's service type).
48
+ * The request is delivered asynchronously. The endpoint returns immediately with
49
+ * `{ "success": true, "message": "Location request sent" }` and does not return
50
+ * coordinates.
51
+ *
52
+ * Location requests only work in **1:1 iMessage chats** (Apple limitation):
53
+ *
54
+ * - Group chats (any service) return `409` with code `2016`
55
+ * (`GroupChatNotSupported`).
56
+ * - 1:1 SMS and RCS chats return `409` with code `2017`
57
+ * (`ChatServiceNotSupported`).
22
58
  *
23
59
  * @example
24
60
  * ```ts
@@ -42,7 +78,12 @@ export declare class Location extends APIResource {
42
78
  * `properties.handle` identifies the user.
43
79
  *
44
80
  * Returns an empty `data.features` array if no one is sharing or no location data
45
- * is available yet.
81
+ * is available yet. If sharing started but this stays empty, see the **Location
82
+ * Sharing** overview.
83
+ *
84
+ * Poll this endpoint to track a moving contact. `properties.updated_at` reflects
85
+ * when each participant's location was last updated. There is no coordinate-update
86
+ * webhook. See the **Location Sharing** overview for polling guidance.
46
87
  *
47
88
  * @example
48
89
  * ```ts
@@ -1 +1 @@
1
- {"version":3,"file":"location.d.mts","sourceRoot":"","sources":["../../src/resources/chats/location.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAClD,OAAO,EAAE,UAAU,EAAE,mCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,2CAAuC;AAGhE;;;;;;;;;GASG;AACH,qBAAa,QAAS,SAAQ,WAAW;IACvC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,uBAAuB,CAAC;IAItF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,uBAAuB,CAAC;CAMxF;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,uBAAuB,CAAC,IAAI,CAAC;IAEnC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,yBAAiB,uBAAuB,CAAC;IACvC,UAAiB,IAAI;QACnB,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAE9B,IAAI,EAAE,mBAAmB,CAAC;KAC3B;IAED,UAAiB,IAAI,CAAC;QACpB,UAAiB,OAAO;YACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC;YAE3B,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC;YAE/B,IAAI,EAAE,SAAS,CAAC;SACjB;QAED,UAAiB,OAAO,CAAC;YACvB,UAAiB,QAAQ;gBACvB;;mBAEG;gBACH,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBAE3B,IAAI,EAAE,OAAO,CAAC;aACf;YAED,UAAiB,UAAU;gBACzB;;mBAEG;gBACH,MAAM,EAAE,MAAM,CAAC;gBAEf;;mBAEG;gBACH,OAAO,CAAC,EAAE,MAAM,CAAC;gBAEjB;;mBAEG;gBACH,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAElB;;mBAEG;gBACH,UAAU,CAAC,EAAE,MAAM,CAAC;aACrB;SACF;KACF;CACF;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IAChC,OAAO,EACL,KAAK,uBAAuB,IAAI,uBAAuB,EACvD,KAAK,uBAAuB,IAAI,uBAAuB,GACxD,CAAC;CACH"}
1
+ {"version":3,"file":"location.d.mts","sourceRoot":"","sources":["../../src/resources/chats/location.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAClD,OAAO,EAAE,UAAU,EAAE,mCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,2CAAuC;AAGhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,QAAS,SAAQ,WAAW;IACvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,uBAAuB,CAAC;IAItF;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,uBAAuB,CAAC;CAMxF;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,uBAAuB,CAAC,IAAI,CAAC;IAEnC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,yBAAiB,uBAAuB,CAAC;IACvC,UAAiB,IAAI;QACnB,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAE9B,IAAI,EAAE,mBAAmB,CAAC;KAC3B;IAED,UAAiB,IAAI,CAAC;QACpB,UAAiB,OAAO;YACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC;YAE3B,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC;YAE/B,IAAI,EAAE,SAAS,CAAC;SACjB;QAED,UAAiB,OAAO,CAAC;YACvB,UAAiB,QAAQ;gBACvB;;mBAEG;gBACH,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBAE3B,IAAI,EAAE,OAAO,CAAC;aACf;YAED,UAAiB,UAAU;gBACzB;;mBAEG;gBACH,MAAM,EAAE,MAAM,CAAC;gBAEf;;mBAEG;gBACH,OAAO,CAAC,EAAE,MAAM,CAAC;gBAEjB;;mBAEG;gBACH,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAElB;;mBAEG;gBACH,UAAU,CAAC,EAAE,MAAM,CAAC;aACrB;SACF;KACF;CACF;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IAChC,OAAO,EACL,KAAK,uBAAuB,IAAI,uBAAuB,EACvD,KAAK,uBAAuB,IAAI,uBAAuB,GACxD,CAAC;CACH"}
@@ -2,23 +2,59 @@ import { APIResource } from "../../core/resource.js";
2
2
  import { APIPromise } from "../../core/api-promise.js";
3
3
  import { RequestOptions } from "../../internal/request-options.js";
4
4
  /**
5
- * Request and retrieve real-time location data via iMessage.
6
- *
7
- * Use these endpoints to request a contact's location, retrieve location data
8
- * for contacts who are sharing with you, and subscribe to webhooks when someone
9
- * starts or stops sharing their location.
5
+ * Request a contact's location, retrieve location for contacts sharing with you,
6
+ * and subscribe to webhooks when someone starts or stops sharing.
10
7
  *
11
8
  * **Coordinates** are returned in [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) format:
12
9
  * `[longitude, latitude]` or `[longitude, latitude, altitude]` if altitude is available.
10
+ *
11
+ * ### Reading location is poll-based
12
+ *
13
+ * Poll `GET /v3/chats/{chatId}/location` whenever you need the latest position.
14
+ * **There is no webhook that pushes updated coordinates** — the
15
+ * `location.sharing.started` / `location.sharing.stopped` webhooks fire only when a
16
+ * contact begins or ends sharing, not on each position update. To track a moving
17
+ * contact, poll the `GET` endpoint.
18
+ *
19
+ * ### Freshness
20
+ *
21
+ * Each feature's `properties.updated_at` tells you when that participant's
22
+ * location was last updated — use it to judge freshness.
23
+ *
24
+ * ### Polling guidance
25
+ *
26
+ * Locations refresh on Apple's cadence, not per request — polling faster than a
27
+ * participant's location actually updates just returns the same position. Poll at a
28
+ * modest interval (for example, once every few minutes per chat) rather than
29
+ * continuously.
30
+ *
31
+ * ### Why is location empty after `location.sharing.started` fired?
32
+ *
33
+ * If the contact started sharing from the **standalone Find My app** instead of the
34
+ * Messages conversation, the share may be tied to their **Apple ID email** rather
35
+ * than their phone number — the webhook's `shared_by` field shows the email in that
36
+ * case. Location is readable only through a chat with the handle that shared, so
37
+ * `GET /v3/chats/{chatId}/location` on the phone-number chat stays empty.
38
+ *
39
+ * The fix: have the contact stop sharing and re-share from **Find My inside the
40
+ * Messages conversation** with your number.
13
41
  */
14
42
  export declare class Location extends APIResource {
15
43
  /**
16
- * Send a location sharing request to a contact. They will receive an iMessage
17
- * prompt asking them to share their location.
44
+ * Request a contact in a chat to share their location. They receive an iMessage
45
+ * prompt and must accept before any location is available; once they do, read
46
+ * their location coordinates with `GET /v3/chats/{chatId}/location`.
18
47
  *
19
- * Location requests only work in **1:1 iMessage chats** (Apple limitation).
20
- * Attempting to request location in a group chat, or in an SMS or RCS chat,
21
- * returns `409` (Operation not supported on this chat's service type).
48
+ * The request is delivered asynchronously. The endpoint returns immediately with
49
+ * `{ "success": true, "message": "Location request sent" }` and does not return
50
+ * coordinates.
51
+ *
52
+ * Location requests only work in **1:1 iMessage chats** (Apple limitation):
53
+ *
54
+ * - Group chats (any service) return `409` with code `2016`
55
+ * (`GroupChatNotSupported`).
56
+ * - 1:1 SMS and RCS chats return `409` with code `2017`
57
+ * (`ChatServiceNotSupported`).
22
58
  *
23
59
  * @example
24
60
  * ```ts
@@ -42,7 +78,12 @@ export declare class Location extends APIResource {
42
78
  * `properties.handle` identifies the user.
43
79
  *
44
80
  * Returns an empty `data.features` array if no one is sharing or no location data
45
- * is available yet.
81
+ * is available yet. If sharing started but this stays empty, see the **Location
82
+ * Sharing** overview.
83
+ *
84
+ * Poll this endpoint to track a moving contact. `properties.updated_at` reflects
85
+ * when each participant's location was last updated. There is no coordinate-update
86
+ * webhook. See the **Location Sharing** overview for polling guidance.
46
87
  *
47
88
  * @example
48
89
  * ```ts
@@ -1 +1 @@
1
- {"version":3,"file":"location.d.ts","sourceRoot":"","sources":["../../src/resources/chats/location.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,+BAA4B;AAClD,OAAO,EAAE,UAAU,EAAE,kCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,0CAAuC;AAGhE;;;;;;;;;GASG;AACH,qBAAa,QAAS,SAAQ,WAAW;IACvC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,uBAAuB,CAAC;IAItF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,uBAAuB,CAAC;CAMxF;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,uBAAuB,CAAC,IAAI,CAAC;IAEnC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,yBAAiB,uBAAuB,CAAC;IACvC,UAAiB,IAAI;QACnB,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAE9B,IAAI,EAAE,mBAAmB,CAAC;KAC3B;IAED,UAAiB,IAAI,CAAC;QACpB,UAAiB,OAAO;YACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC;YAE3B,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC;YAE/B,IAAI,EAAE,SAAS,CAAC;SACjB;QAED,UAAiB,OAAO,CAAC;YACvB,UAAiB,QAAQ;gBACvB;;mBAEG;gBACH,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBAE3B,IAAI,EAAE,OAAO,CAAC;aACf;YAED,UAAiB,UAAU;gBACzB;;mBAEG;gBACH,MAAM,EAAE,MAAM,CAAC;gBAEf;;mBAEG;gBACH,OAAO,CAAC,EAAE,MAAM,CAAC;gBAEjB;;mBAEG;gBACH,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAElB;;mBAEG;gBACH,UAAU,CAAC,EAAE,MAAM,CAAC;aACrB;SACF;KACF;CACF;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IAChC,OAAO,EACL,KAAK,uBAAuB,IAAI,uBAAuB,EACvD,KAAK,uBAAuB,IAAI,uBAAuB,GACxD,CAAC;CACH"}
1
+ {"version":3,"file":"location.d.ts","sourceRoot":"","sources":["../../src/resources/chats/location.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,+BAA4B;AAClD,OAAO,EAAE,UAAU,EAAE,kCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,0CAAuC;AAGhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,QAAS,SAAQ,WAAW;IACvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,uBAAuB,CAAC;IAItF;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,uBAAuB,CAAC;CAMxF;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,uBAAuB,CAAC,IAAI,CAAC;IAEnC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,yBAAiB,uBAAuB,CAAC;IACvC,UAAiB,IAAI;QACnB,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAE9B,IAAI,EAAE,mBAAmB,CAAC;KAC3B;IAED,UAAiB,IAAI,CAAC;QACpB,UAAiB,OAAO;YACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC;YAE3B,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC;YAE/B,IAAI,EAAE,SAAS,CAAC;SACjB;QAED,UAAiB,OAAO,CAAC;YACvB,UAAiB,QAAQ;gBACvB;;mBAEG;gBACH,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBAE3B,IAAI,EAAE,OAAO,CAAC;aACf;YAED,UAAiB,UAAU;gBACzB;;mBAEG;gBACH,MAAM,EAAE,MAAM,CAAC;gBAEf;;mBAEG;gBACH,OAAO,CAAC,EAAE,MAAM,CAAC;gBAEjB;;mBAEG;gBACH,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAElB;;mBAEG;gBACH,UAAU,CAAC,EAAE,MAAM,CAAC;aACrB;SACF;KACF;CACF;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IAChC,OAAO,EACL,KAAK,uBAAuB,IAAI,uBAAuB,EACvD,KAAK,uBAAuB,IAAI,uBAAuB,GACxD,CAAC;CACH"}
@@ -6,23 +6,59 @@ const resource_1 = require("../../core/resource.js");
6
6
  const headers_1 = require("../../internal/headers.js");
7
7
  const path_1 = require("../../internal/utils/path.js");
8
8
  /**
9
- * Request and retrieve real-time location data via iMessage.
10
- *
11
- * Use these endpoints to request a contact's location, retrieve location data
12
- * for contacts who are sharing with you, and subscribe to webhooks when someone
13
- * starts or stops sharing their location.
9
+ * Request a contact's location, retrieve location for contacts sharing with you,
10
+ * and subscribe to webhooks when someone starts or stops sharing.
14
11
  *
15
12
  * **Coordinates** are returned in [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) format:
16
13
  * `[longitude, latitude]` or `[longitude, latitude, altitude]` if altitude is available.
14
+ *
15
+ * ### Reading location is poll-based
16
+ *
17
+ * Poll `GET /v3/chats/{chatId}/location` whenever you need the latest position.
18
+ * **There is no webhook that pushes updated coordinates** — the
19
+ * `location.sharing.started` / `location.sharing.stopped` webhooks fire only when a
20
+ * contact begins or ends sharing, not on each position update. To track a moving
21
+ * contact, poll the `GET` endpoint.
22
+ *
23
+ * ### Freshness
24
+ *
25
+ * Each feature's `properties.updated_at` tells you when that participant's
26
+ * location was last updated — use it to judge freshness.
27
+ *
28
+ * ### Polling guidance
29
+ *
30
+ * Locations refresh on Apple's cadence, not per request — polling faster than a
31
+ * participant's location actually updates just returns the same position. Poll at a
32
+ * modest interval (for example, once every few minutes per chat) rather than
33
+ * continuously.
34
+ *
35
+ * ### Why is location empty after `location.sharing.started` fired?
36
+ *
37
+ * If the contact started sharing from the **standalone Find My app** instead of the
38
+ * Messages conversation, the share may be tied to their **Apple ID email** rather
39
+ * than their phone number — the webhook's `shared_by` field shows the email in that
40
+ * case. Location is readable only through a chat with the handle that shared, so
41
+ * `GET /v3/chats/{chatId}/location` on the phone-number chat stays empty.
42
+ *
43
+ * The fix: have the contact stop sharing and re-share from **Find My inside the
44
+ * Messages conversation** with your number.
17
45
  */
18
46
  class Location extends resource_1.APIResource {
19
47
  /**
20
- * Send a location sharing request to a contact. They will receive an iMessage
21
- * prompt asking them to share their location.
48
+ * Request a contact in a chat to share their location. They receive an iMessage
49
+ * prompt and must accept before any location is available; once they do, read
50
+ * their location coordinates with `GET /v3/chats/{chatId}/location`.
22
51
  *
23
- * Location requests only work in **1:1 iMessage chats** (Apple limitation).
24
- * Attempting to request location in a group chat, or in an SMS or RCS chat,
25
- * returns `409` (Operation not supported on this chat's service type).
52
+ * The request is delivered asynchronously. The endpoint returns immediately with
53
+ * `{ "success": true, "message": "Location request sent" }` and does not return
54
+ * coordinates.
55
+ *
56
+ * Location requests only work in **1:1 iMessage chats** (Apple limitation):
57
+ *
58
+ * - Group chats (any service) return `409` with code `2016`
59
+ * (`GroupChatNotSupported`).
60
+ * - 1:1 SMS and RCS chats return `409` with code `2017`
61
+ * (`ChatServiceNotSupported`).
26
62
  *
27
63
  * @example
28
64
  * ```ts
@@ -48,7 +84,12 @@ class Location extends resource_1.APIResource {
48
84
  * `properties.handle` identifies the user.
49
85
  *
50
86
  * Returns an empty `data.features` array if no one is sharing or no location data
51
- * is available yet.
87
+ * is available yet. If sharing started but this stays empty, see the **Location
88
+ * Sharing** overview.
89
+ *
90
+ * Poll this endpoint to track a moving contact. `properties.updated_at` reflects
91
+ * when each participant's location was last updated. There is no coordinate-update
92
+ * webhook. See the **Location Sharing** overview for polling guidance.
52
93
  *
53
94
  * @example
54
95
  * ```ts
@@ -1 +1 @@
1
- {"version":3,"file":"location.js","sourceRoot":"","sources":["../../src/resources/chats/location.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,qDAAkD;AAElD,uDAAsD;AAEtD,uDAAiD;AAEjD;;;;;;;;;GASG;AACH,MAAa,QAAS,SAAQ,sBAAW;IACvC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAAc,EAAE,OAAwB;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAA,WAAI,EAAA,aAAa,MAAM,mBAAmB,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,MAAc,EAAE,OAAwB;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,aAAa,MAAM,WAAW,EAAE;YAC1D,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,sBAAsB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC9E,CAAC,CAAC;IACL,CAAC;CACF;AAlDD,4BAkDC"}
1
+ {"version":3,"file":"location.js","sourceRoot":"","sources":["../../src/resources/chats/location.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,qDAAkD;AAElD,uDAAsD;AAEtD,uDAAiD;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAa,QAAS,SAAQ,sBAAW;IACvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,MAAc,EAAE,OAAwB;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAA,WAAI,EAAA,aAAa,MAAM,mBAAmB,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,QAAQ,CAAC,MAAc,EAAE,OAAwB;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,aAAa,MAAM,WAAW,EAAE;YAC1D,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,sBAAsB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC9E,CAAC,CAAC;IACL,CAAC;CACF;AA/DD,4BA+DC"}
@@ -3,23 +3,59 @@ import { APIResource } from "../../core/resource.mjs";
3
3
  import { buildHeaders } from "../../internal/headers.mjs";
4
4
  import { path } from "../../internal/utils/path.mjs";
5
5
  /**
6
- * Request and retrieve real-time location data via iMessage.
7
- *
8
- * Use these endpoints to request a contact's location, retrieve location data
9
- * for contacts who are sharing with you, and subscribe to webhooks when someone
10
- * starts or stops sharing their location.
6
+ * Request a contact's location, retrieve location for contacts sharing with you,
7
+ * and subscribe to webhooks when someone starts or stops sharing.
11
8
  *
12
9
  * **Coordinates** are returned in [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946) format:
13
10
  * `[longitude, latitude]` or `[longitude, latitude, altitude]` if altitude is available.
11
+ *
12
+ * ### Reading location is poll-based
13
+ *
14
+ * Poll `GET /v3/chats/{chatId}/location` whenever you need the latest position.
15
+ * **There is no webhook that pushes updated coordinates** — the
16
+ * `location.sharing.started` / `location.sharing.stopped` webhooks fire only when a
17
+ * contact begins or ends sharing, not on each position update. To track a moving
18
+ * contact, poll the `GET` endpoint.
19
+ *
20
+ * ### Freshness
21
+ *
22
+ * Each feature's `properties.updated_at` tells you when that participant's
23
+ * location was last updated — use it to judge freshness.
24
+ *
25
+ * ### Polling guidance
26
+ *
27
+ * Locations refresh on Apple's cadence, not per request — polling faster than a
28
+ * participant's location actually updates just returns the same position. Poll at a
29
+ * modest interval (for example, once every few minutes per chat) rather than
30
+ * continuously.
31
+ *
32
+ * ### Why is location empty after `location.sharing.started` fired?
33
+ *
34
+ * If the contact started sharing from the **standalone Find My app** instead of the
35
+ * Messages conversation, the share may be tied to their **Apple ID email** rather
36
+ * than their phone number — the webhook's `shared_by` field shows the email in that
37
+ * case. Location is readable only through a chat with the handle that shared, so
38
+ * `GET /v3/chats/{chatId}/location` on the phone-number chat stays empty.
39
+ *
40
+ * The fix: have the contact stop sharing and re-share from **Find My inside the
41
+ * Messages conversation** with your number.
14
42
  */
15
43
  export class Location extends APIResource {
16
44
  /**
17
- * Send a location sharing request to a contact. They will receive an iMessage
18
- * prompt asking them to share their location.
45
+ * Request a contact in a chat to share their location. They receive an iMessage
46
+ * prompt and must accept before any location is available; once they do, read
47
+ * their location coordinates with `GET /v3/chats/{chatId}/location`.
19
48
  *
20
- * Location requests only work in **1:1 iMessage chats** (Apple limitation).
21
- * Attempting to request location in a group chat, or in an SMS or RCS chat,
22
- * returns `409` (Operation not supported on this chat's service type).
49
+ * The request is delivered asynchronously. The endpoint returns immediately with
50
+ * `{ "success": true, "message": "Location request sent" }` and does not return
51
+ * coordinates.
52
+ *
53
+ * Location requests only work in **1:1 iMessage chats** (Apple limitation):
54
+ *
55
+ * - Group chats (any service) return `409` with code `2016`
56
+ * (`GroupChatNotSupported`).
57
+ * - 1:1 SMS and RCS chats return `409` with code `2017`
58
+ * (`ChatServiceNotSupported`).
23
59
  *
24
60
  * @example
25
61
  * ```ts
@@ -45,7 +81,12 @@ export class Location extends APIResource {
45
81
  * `properties.handle` identifies the user.
46
82
  *
47
83
  * Returns an empty `data.features` array if no one is sharing or no location data
48
- * is available yet.
84
+ * is available yet. If sharing started but this stays empty, see the **Location
85
+ * Sharing** overview.
86
+ *
87
+ * Poll this endpoint to track a moving contact. `properties.updated_at` reflects
88
+ * when each participant's location was last updated. There is no coordinate-update
89
+ * webhook. See the **Location Sharing** overview for polling guidance.
49
90
  *
50
91
  * @example
51
92
  * ```ts
@@ -1 +1 @@
1
- {"version":3,"file":"location.mjs","sourceRoot":"","sources":["../../src/resources/chats/location.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAElD,OAAO,EAAE,YAAY,EAAE,mCAA+B;AAEtD,OAAO,EAAE,IAAI,EAAE,sCAAkC;AAEjD;;;;;;;;;GASG;AACH,MAAM,OAAO,QAAS,SAAQ,WAAW;IACvC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,MAAc,EAAE,OAAwB;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAA,aAAa,MAAM,mBAAmB,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,MAAc,EAAE,OAAwB;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,aAAa,MAAM,WAAW,EAAE;YAC1D,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,sBAAsB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC9E,CAAC,CAAC;IACL,CAAC;CACF"}
1
+ {"version":3,"file":"location.mjs","sourceRoot":"","sources":["../../src/resources/chats/location.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAElD,OAAO,EAAE,YAAY,EAAE,mCAA+B;AAEtD,OAAO,EAAE,IAAI,EAAE,sCAAkC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,OAAO,QAAS,SAAQ,WAAW;IACvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,MAAc,EAAE,OAAwB;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAA,aAAa,MAAM,mBAAmB,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,QAAQ,CAAC,MAAc,EAAE,OAAwB;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,aAAa,MAAM,WAAW,EAAE;YAC1D,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,sBAAsB,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC9E,CAAC,CAAC;IACL,CAAC;CACF"}
@@ -23,14 +23,20 @@ export declare class Typing extends APIResource {
23
23
  /**
24
24
  * Send a typing indicator to show that someone is typing in the chat.
25
25
  *
26
- * ## Behavior & Limitations
26
+ * ## Behavior
27
27
  *
28
- * Typing indicators are best-effort signals with the following limitations:
28
+ * Typing indicators are best-effort signals that behave as follows:
29
29
  *
30
- * - **Active conversations only:** The recipient must have sent or received a
31
- * message in this chat within the **last 5 minutes**. If the chat is inactive,
32
- * the request is still accepted (`204`) but the indicator will not reach the
33
- * recipient's device.
30
+ * - **iMessage chats only:** Typing indicators are only supported for iMessage
31
+ * chats. Requests for RCS or SMS chats are accepted (`204`) but no indicator is
32
+ * delivered.
33
+ *
34
+ * - **Send a message first for reliable delivery:** Typing indicators are
35
+ * best-effort. If you have not sent a message in this chat recently (roughly the
36
+ * **last 5 minutes**), a typing indicator may not reach the recipient — the
37
+ * request is still accepted (`204`), but delivery is not deterministic. Once you
38
+ * have sent a message in the chat, typing indicators reliably reach the
39
+ * recipient.
34
40
  *
35
41
  * - **No delivery guarantee:** Even for active chats, a `204` response only
36
42
  * indicates the request was accepted for processing.
@@ -38,6 +44,34 @@ export declare class Typing extends APIResource {
38
44
  * - **Group chats not supported:** Attempting to start a typing indicator in a
39
45
  * group chat will return a `403` error.
40
46
  *
47
+ * ## Duration & keeping it visible
48
+ *
49
+ * - A single call shows the indicator for about **85–90 seconds**, then it clears
50
+ * automatically.
51
+ *
52
+ * - To keep it visible longer, call this endpoint again every **60 seconds**. Each
53
+ * call refreshes the indicator so it stays visible continuously.
54
+ *
55
+ * - Sending a message clears the indicator.
56
+ *
57
+ * - To resume typing after sending a message, call this endpoint again.
58
+ *
59
+ * - Incoming messages do not affect the indicator.
60
+ *
61
+ * ## Recipient re-opening the chat
62
+ *
63
+ * If the recipient brings their messaging app to the foreground while the chat has
64
+ * an unread message, their device clears any showing typing indicator. Calling
65
+ * this endpoint again on its own may not bring it back. To make it reappear,
66
+ * either send a message, or call `DELETE /v3/chats/{chatId}/typing` (stop) and
67
+ * then call start typing again.
68
+ *
69
+ * ## Recommended usage
70
+ *
71
+ * Call this endpoint when composing begins, call it again every 60 seconds while
72
+ * composing, and send the message to clear the indicator. To clear the indicator
73
+ * without sending a message, call `DELETE /v3/chats/{chatId}/typing`.
74
+ *
41
75
  * @example
42
76
  * ```ts
43
77
  * await client.chats.typing.start(
@@ -47,12 +81,14 @@ export declare class Typing extends APIResource {
47
81
  */
48
82
  start(chatID: string, options?: RequestOptions): APIPromise<void>;
49
83
  /**
50
- * Stop the typing indicator for the chat.
84
+ * Immediately clears the typing indicator for the chat, without sending a message.
51
85
  *
52
- * Typing indicators are automatically stopped when a message is sent, so calling
53
- * this endpoint after sending a message is unnecessary.
86
+ * The typing indicator also clears automatically when you send a message, or about
87
+ * 85–90 seconds after the last `POST /v3/chats/{chatId}/typing` (start typing)
88
+ * request.
54
89
  *
55
- * See the `POST` endpoint above for behavior details and limitations.
90
+ * See the start typing endpoint (`POST /v3/chats/{chatId}/typing`) above for
91
+ * behavior details.
56
92
  *
57
93
  * **Note:** Group chats are not supported and will return a `403` error.
58
94
  *
@@ -1 +1 @@
1
- {"version":3,"file":"typing.d.mts","sourceRoot":"","sources":["../../src/resources/chats/typing.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAClD,OAAO,EAAE,UAAU,EAAE,mCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,2CAAuC;AAGhE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAO,SAAQ,WAAW;IACrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAOjE;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;CAMjE"}
1
+ {"version":3,"file":"typing.d.mts","sourceRoot":"","sources":["../../src/resources/chats/typing.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAClD,OAAO,EAAE,UAAU,EAAE,mCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,2CAAuC;AAGhE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAO,SAAQ,WAAW;IACrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAOjE;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;CAMjE"}
@@ -23,14 +23,20 @@ export declare class Typing extends APIResource {
23
23
  /**
24
24
  * Send a typing indicator to show that someone is typing in the chat.
25
25
  *
26
- * ## Behavior & Limitations
26
+ * ## Behavior
27
27
  *
28
- * Typing indicators are best-effort signals with the following limitations:
28
+ * Typing indicators are best-effort signals that behave as follows:
29
29
  *
30
- * - **Active conversations only:** The recipient must have sent or received a
31
- * message in this chat within the **last 5 minutes**. If the chat is inactive,
32
- * the request is still accepted (`204`) but the indicator will not reach the
33
- * recipient's device.
30
+ * - **iMessage chats only:** Typing indicators are only supported for iMessage
31
+ * chats. Requests for RCS or SMS chats are accepted (`204`) but no indicator is
32
+ * delivered.
33
+ *
34
+ * - **Send a message first for reliable delivery:** Typing indicators are
35
+ * best-effort. If you have not sent a message in this chat recently (roughly the
36
+ * **last 5 minutes**), a typing indicator may not reach the recipient — the
37
+ * request is still accepted (`204`), but delivery is not deterministic. Once you
38
+ * have sent a message in the chat, typing indicators reliably reach the
39
+ * recipient.
34
40
  *
35
41
  * - **No delivery guarantee:** Even for active chats, a `204` response only
36
42
  * indicates the request was accepted for processing.
@@ -38,6 +44,34 @@ export declare class Typing extends APIResource {
38
44
  * - **Group chats not supported:** Attempting to start a typing indicator in a
39
45
  * group chat will return a `403` error.
40
46
  *
47
+ * ## Duration & keeping it visible
48
+ *
49
+ * - A single call shows the indicator for about **85–90 seconds**, then it clears
50
+ * automatically.
51
+ *
52
+ * - To keep it visible longer, call this endpoint again every **60 seconds**. Each
53
+ * call refreshes the indicator so it stays visible continuously.
54
+ *
55
+ * - Sending a message clears the indicator.
56
+ *
57
+ * - To resume typing after sending a message, call this endpoint again.
58
+ *
59
+ * - Incoming messages do not affect the indicator.
60
+ *
61
+ * ## Recipient re-opening the chat
62
+ *
63
+ * If the recipient brings their messaging app to the foreground while the chat has
64
+ * an unread message, their device clears any showing typing indicator. Calling
65
+ * this endpoint again on its own may not bring it back. To make it reappear,
66
+ * either send a message, or call `DELETE /v3/chats/{chatId}/typing` (stop) and
67
+ * then call start typing again.
68
+ *
69
+ * ## Recommended usage
70
+ *
71
+ * Call this endpoint when composing begins, call it again every 60 seconds while
72
+ * composing, and send the message to clear the indicator. To clear the indicator
73
+ * without sending a message, call `DELETE /v3/chats/{chatId}/typing`.
74
+ *
41
75
  * @example
42
76
  * ```ts
43
77
  * await client.chats.typing.start(
@@ -47,12 +81,14 @@ export declare class Typing extends APIResource {
47
81
  */
48
82
  start(chatID: string, options?: RequestOptions): APIPromise<void>;
49
83
  /**
50
- * Stop the typing indicator for the chat.
84
+ * Immediately clears the typing indicator for the chat, without sending a message.
51
85
  *
52
- * Typing indicators are automatically stopped when a message is sent, so calling
53
- * this endpoint after sending a message is unnecessary.
86
+ * The typing indicator also clears automatically when you send a message, or about
87
+ * 85–90 seconds after the last `POST /v3/chats/{chatId}/typing` (start typing)
88
+ * request.
54
89
  *
55
- * See the `POST` endpoint above for behavior details and limitations.
90
+ * See the start typing endpoint (`POST /v3/chats/{chatId}/typing`) above for
91
+ * behavior details.
56
92
  *
57
93
  * **Note:** Group chats are not supported and will return a `403` error.
58
94
  *
@@ -1 +1 @@
1
- {"version":3,"file":"typing.d.ts","sourceRoot":"","sources":["../../src/resources/chats/typing.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,+BAA4B;AAClD,OAAO,EAAE,UAAU,EAAE,kCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,0CAAuC;AAGhE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAO,SAAQ,WAAW;IACrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAOjE;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;CAMjE"}
1
+ {"version":3,"file":"typing.d.ts","sourceRoot":"","sources":["../../src/resources/chats/typing.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,+BAA4B;AAClD,OAAO,EAAE,UAAU,EAAE,kCAA+B;AAEpD,OAAO,EAAE,cAAc,EAAE,0CAAuC;AAGhE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAO,SAAQ,WAAW;IACrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;IAOjE;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC;CAMjE"}
@@ -27,14 +27,20 @@ class Typing extends resource_1.APIResource {
27
27
  /**
28
28
  * Send a typing indicator to show that someone is typing in the chat.
29
29
  *
30
- * ## Behavior & Limitations
30
+ * ## Behavior
31
31
  *
32
- * Typing indicators are best-effort signals with the following limitations:
32
+ * Typing indicators are best-effort signals that behave as follows:
33
33
  *
34
- * - **Active conversations only:** The recipient must have sent or received a
35
- * message in this chat within the **last 5 minutes**. If the chat is inactive,
36
- * the request is still accepted (`204`) but the indicator will not reach the
37
- * recipient's device.
34
+ * - **iMessage chats only:** Typing indicators are only supported for iMessage
35
+ * chats. Requests for RCS or SMS chats are accepted (`204`) but no indicator is
36
+ * delivered.
37
+ *
38
+ * - **Send a message first for reliable delivery:** Typing indicators are
39
+ * best-effort. If you have not sent a message in this chat recently (roughly the
40
+ * **last 5 minutes**), a typing indicator may not reach the recipient — the
41
+ * request is still accepted (`204`), but delivery is not deterministic. Once you
42
+ * have sent a message in the chat, typing indicators reliably reach the
43
+ * recipient.
38
44
  *
39
45
  * - **No delivery guarantee:** Even for active chats, a `204` response only
40
46
  * indicates the request was accepted for processing.
@@ -42,6 +48,34 @@ class Typing extends resource_1.APIResource {
42
48
  * - **Group chats not supported:** Attempting to start a typing indicator in a
43
49
  * group chat will return a `403` error.
44
50
  *
51
+ * ## Duration & keeping it visible
52
+ *
53
+ * - A single call shows the indicator for about **85–90 seconds**, then it clears
54
+ * automatically.
55
+ *
56
+ * - To keep it visible longer, call this endpoint again every **60 seconds**. Each
57
+ * call refreshes the indicator so it stays visible continuously.
58
+ *
59
+ * - Sending a message clears the indicator.
60
+ *
61
+ * - To resume typing after sending a message, call this endpoint again.
62
+ *
63
+ * - Incoming messages do not affect the indicator.
64
+ *
65
+ * ## Recipient re-opening the chat
66
+ *
67
+ * If the recipient brings their messaging app to the foreground while the chat has
68
+ * an unread message, their device clears any showing typing indicator. Calling
69
+ * this endpoint again on its own may not bring it back. To make it reappear,
70
+ * either send a message, or call `DELETE /v3/chats/{chatId}/typing` (stop) and
71
+ * then call start typing again.
72
+ *
73
+ * ## Recommended usage
74
+ *
75
+ * Call this endpoint when composing begins, call it again every 60 seconds while
76
+ * composing, and send the message to clear the indicator. To clear the indicator
77
+ * without sending a message, call `DELETE /v3/chats/{chatId}/typing`.
78
+ *
45
79
  * @example
46
80
  * ```ts
47
81
  * await client.chats.typing.start(
@@ -56,12 +90,14 @@ class Typing extends resource_1.APIResource {
56
90
  });
57
91
  }
58
92
  /**
59
- * Stop the typing indicator for the chat.
93
+ * Immediately clears the typing indicator for the chat, without sending a message.
60
94
  *
61
- * Typing indicators are automatically stopped when a message is sent, so calling
62
- * this endpoint after sending a message is unnecessary.
95
+ * The typing indicator also clears automatically when you send a message, or about
96
+ * 85–90 seconds after the last `POST /v3/chats/{chatId}/typing` (start typing)
97
+ * request.
63
98
  *
64
- * See the `POST` endpoint above for behavior details and limitations.
99
+ * See the start typing endpoint (`POST /v3/chats/{chatId}/typing`) above for
100
+ * behavior details.
65
101
  *
66
102
  * **Note:** Group chats are not supported and will return a `403` error.
67
103
  *
@@ -1 +1 @@
1
- {"version":3,"file":"typing.js","sourceRoot":"","sources":["../../src/resources/chats/typing.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,qDAAkD;AAElD,uDAAsD;AAEtD,uDAAiD;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,MAAO,SAAQ,sBAAW;IACrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,CAAC,MAAc,EAAE,OAAwB;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAA,WAAI,EAAA,aAAa,MAAM,SAAS,EAAE;YACzD,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,MAAc,EAAE,OAAwB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,aAAa,MAAM,SAAS,EAAE;YAC3D,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AAxDD,wBAwDC"}
1
+ {"version":3,"file":"typing.js","sourceRoot":"","sources":["../../src/resources/chats/typing.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,qDAAkD;AAElD,uDAAsD;AAEtD,uDAAiD;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,MAAO,SAAQ,sBAAW;IACrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACH,KAAK,CAAC,MAAc,EAAE,OAAwB;QAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAA,WAAI,EAAA,aAAa,MAAM,SAAS,EAAE;YACzD,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,CAAC,MAAc,EAAE,OAAwB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,aAAa,MAAM,SAAS,EAAE;YAC3D,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AA5FD,wBA4FC"}