influship 0.10.2 → 0.12.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 (48) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/client.d.mts +6 -0
  3. package/client.d.mts.map +1 -1
  4. package/client.d.ts +6 -0
  5. package/client.d.ts.map +1 -1
  6. package/client.js +6 -0
  7. package/client.js.map +1 -1
  8. package/client.mjs +6 -0
  9. package/client.mjs.map +1 -1
  10. package/package.json +1 -1
  11. package/resources/creator-emails.d.mts +162 -0
  12. package/resources/creator-emails.d.mts.map +1 -0
  13. package/resources/creator-emails.d.ts +162 -0
  14. package/resources/creator-emails.d.ts.map +1 -0
  15. package/resources/creator-emails.js +26 -0
  16. package/resources/creator-emails.js.map +1 -0
  17. package/resources/creator-emails.mjs +22 -0
  18. package/resources/creator-emails.mjs.map +1 -0
  19. package/resources/index.d.mts +1 -0
  20. package/resources/index.d.mts.map +1 -1
  21. package/resources/index.d.ts +1 -0
  22. package/resources/index.d.ts.map +1 -1
  23. package/resources/index.js +3 -1
  24. package/resources/index.js.map +1 -1
  25. package/resources/index.mjs +1 -0
  26. package/resources/index.mjs.map +1 -1
  27. package/resources/posts.d.mts +28 -7
  28. package/resources/posts.d.mts.map +1 -1
  29. package/resources/posts.d.ts +28 -7
  30. package/resources/posts.d.ts.map +1 -1
  31. package/resources/raw/instagram.d.mts +12 -1
  32. package/resources/raw/instagram.d.mts.map +1 -1
  33. package/resources/raw/instagram.d.ts +12 -1
  34. package/resources/raw/instagram.d.ts.map +1 -1
  35. package/resources/raw/instagram.js +11 -0
  36. package/resources/raw/instagram.js.map +1 -1
  37. package/resources/raw/instagram.mjs +11 -0
  38. package/resources/raw/instagram.mjs.map +1 -1
  39. package/src/client.ts +16 -0
  40. package/src/resources/creator-emails.ts +195 -0
  41. package/src/resources/index.ts +5 -0
  42. package/src/resources/posts.ts +31 -7
  43. package/src/resources/raw/instagram.ts +13 -2
  44. package/src/version.ts +1 -1
  45. package/version.d.mts +1 -1
  46. package/version.d.ts +1 -1
  47. package/version.js +1 -1
  48. package/version.mjs +1 -1
@@ -17,6 +17,10 @@ class Instagram extends resource_1.APIResource {
17
17
  * **Note:** These fields are only guaranteed on this raw single-post lookup.
18
18
  * Cached post-list endpoints may not include them.
19
19
  *
20
+ * Returns fresh `video_url` (single best stream) and `video_versions[]`
21
+ * (multi-bitrate). These are signed Instagram CDN URLs valid for ~24h — download
22
+ * promptly. For carousels with embedded videos, see `carousel_items[].video_url`.
23
+ *
20
24
  * **Pricing**: 1 credit per post scraped ($0.01)
21
25
  *
22
26
  * @example
@@ -36,6 +40,9 @@ class Instagram extends resource_1.APIResource {
36
40
  * **Note:** Batch post lookup is capped at 20 shortcodes per request and is
37
41
  * charged for every requested shortcode.
38
42
  *
43
+ * Returns fresh `video_url` and `video_versions[]` per post (signed IG CDN URLs,
44
+ * ~24h validity). Batch up to 20 posts at 1 credit ($0.01) each.
45
+ *
39
46
  * **Pricing**: 1 credit per post scraped ($0.01)
40
47
  *
41
48
  * @example
@@ -61,6 +68,10 @@ class Instagram extends resource_1.APIResource {
61
68
  * **Note:** Live scraping is slower than cached data (2-5 seconds) and costs more.
62
69
  * Use cached endpoints when freshness isn't critical.
63
70
  *
71
+ * The `posts[]` array returns up to 12 recent posts with fresh `video_url` for
72
+ * each video post. This is the cheapest bulk-download path: 0.5 credits ($0.005)
73
+ * per profile call vs 1 credit per individual raw-post call.
74
+ *
64
75
  * **Pricing**: 0.5 credits per profile scraped ($0.005)
65
76
  *
66
77
  * @example
@@ -1 +1 @@
1
- {"version":3,"file":"instagram.js","sourceRoot":"","sources":["../../src/resources/raw/instagram.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,qDAAkD;AAKlD,uDAAiD;AAEjD;;GAEG;AACH,MAAa,SAAU,SAAQ,sBAAW;IACxC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,SAAiB,EAAE,OAAwB;QACjD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,0BAA0B,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAA6B,EAAE,OAAwB;QAC9D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAAU,CACR,QAAgB,EAChB,QAAsD,EAAE,EACxD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,6BAA6B,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,aAAa,CACX,SAAiB,EACjB,QAAyD,EAAE,EAC3D,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,gCAAgC,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAClG,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CACZ,IAAmC,EACnC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAClF,CAAC;CACF;AArHD,8BAqHC"}
1
+ {"version":3,"file":"instagram.js","sourceRoot":"","sources":["../../src/resources/raw/instagram.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,qDAAkD;AAKlD,uDAAiD;AAEjD;;GAEG;AACH,MAAa,SAAU,SAAQ,sBAAW;IACxC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,SAAiB,EAAE,OAAwB;QACjD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,0BAA0B,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,IAA6B,EAAE,OAAwB;QAC9D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,UAAU,CACR,QAAgB,EAChB,QAAsD,EAAE,EACxD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,6BAA6B,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,aAAa,CACX,SAAiB,EACjB,QAAyD,EAAE,EAC3D,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,gCAAgC,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAClG,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CACZ,IAAmC,EACnC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAClF,CAAC;CACF;AAhID,8BAgIC"}
@@ -14,6 +14,10 @@ export class Instagram extends APIResource {
14
14
  * **Note:** These fields are only guaranteed on this raw single-post lookup.
15
15
  * Cached post-list endpoints may not include them.
16
16
  *
17
+ * Returns fresh `video_url` (single best stream) and `video_versions[]`
18
+ * (multi-bitrate). These are signed Instagram CDN URLs valid for ~24h — download
19
+ * promptly. For carousels with embedded videos, see `carousel_items[].video_url`.
20
+ *
17
21
  * **Pricing**: 1 credit per post scraped ($0.01)
18
22
  *
19
23
  * @example
@@ -33,6 +37,9 @@ export class Instagram extends APIResource {
33
37
  * **Note:** Batch post lookup is capped at 20 shortcodes per request and is
34
38
  * charged for every requested shortcode.
35
39
  *
40
+ * Returns fresh `video_url` and `video_versions[]` per post (signed IG CDN URLs,
41
+ * ~24h validity). Batch up to 20 posts at 1 credit ($0.01) each.
42
+ *
36
43
  * **Pricing**: 1 credit per post scraped ($0.01)
37
44
  *
38
45
  * @example
@@ -58,6 +65,10 @@ export class Instagram extends APIResource {
58
65
  * **Note:** Live scraping is slower than cached data (2-5 seconds) and costs more.
59
66
  * Use cached endpoints when freshness isn't critical.
60
67
  *
68
+ * The `posts[]` array returns up to 12 recent posts with fresh `video_url` for
69
+ * each video post. This is the cheapest bulk-download path: 0.5 credits ($0.005)
70
+ * per profile call vs 1 credit per individual raw-post call.
71
+ *
61
72
  * **Pricing**: 0.5 credits per profile scraped ($0.005)
62
73
  *
63
74
  * @example
@@ -1 +1 @@
1
- {"version":3,"file":"instagram.mjs","sourceRoot":"","sources":["../../src/resources/raw/instagram.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAKlD,OAAO,EAAE,IAAI,EAAE,sCAAkC;AAEjD;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,WAAW;IACxC;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,SAAiB,EAAE,OAAwB;QACjD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,0BAA0B,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,IAA6B,EAAE,OAAwB;QAC9D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAAU,CACR,QAAgB,EAChB,QAAsD,EAAE,EACxD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,6BAA6B,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,aAAa,CACX,SAAiB,EACjB,QAAyD,EAAE,EAC3D,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,gCAAgC,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAClG,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CACZ,IAAmC,EACnC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAClF,CAAC;CACF"}
1
+ {"version":3,"file":"instagram.mjs","sourceRoot":"","sources":["../../src/resources/raw/instagram.ts"],"names":[],"mappings":"AAAA,sFAAsF;AAEtF,OAAO,EAAE,WAAW,EAAE,gCAA4B;AAKlD,OAAO,EAAE,IAAI,EAAE,sCAAkC;AAEjD;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,WAAW;IACxC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,SAAiB,EAAE,OAAwB;QACjD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,0BAA0B,SAAS,EAAE,EAAE,OAAO,CAAC,CAAC;IAC9E,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,IAA6B,EAAE,OAAwB;QAC9D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,UAAU,CACR,QAAgB,EAChB,QAAsD,EAAE,EACxD,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,6BAA6B,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,aAAa,CACX,SAAiB,EACjB,QAAyD,EAAE,EAC3D,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,gCAAgC,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAClG,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CACZ,IAAmC,EACnC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAClF,CAAC;CACF"}
package/src/client.ts CHANGED
@@ -25,6 +25,11 @@ import {
25
25
  import * as Uploads from './core/uploads';
26
26
  import * as API from './resources/index';
27
27
  import { APIPromise } from './core/api-promise';
28
+ import {
29
+ CreatorEmailLookupParams,
30
+ CreatorEmailLookupResponse,
31
+ CreatorEmails,
32
+ } from './resources/creator-emails';
28
33
  import {
29
34
  CreatorAutocompleteParams,
30
35
  CreatorAutocompleteResponse,
@@ -809,6 +814,10 @@ export class Influship {
809
814
  * Access individual social media profiles with detailed metrics, growth data, and activity information. Profiles are platform-specific accounts linked to creators.
810
815
  */
811
816
  profiles: API.Profiles = new API.Profiles(this);
817
+ /**
818
+ * Look up known creator email addresses by creator ID or social username. Empty or unresolved results are not billable.
819
+ */
820
+ creatorEmails: API.CreatorEmails = new API.CreatorEmails(this);
812
821
  /**
813
822
  * Retrieve and analyze social media posts with engagement metrics, media content, and performance data.
814
823
  */
@@ -820,6 +829,7 @@ Influship.Health = Health;
820
829
  Influship.Creators = Creators;
821
830
  Influship.Search = Search;
822
831
  Influship.Profiles = Profiles;
832
+ Influship.CreatorEmails = CreatorEmails;
823
833
  Influship.Posts = Posts;
824
834
  Influship.Raw = Raw;
825
835
 
@@ -869,6 +879,12 @@ export declare namespace Influship {
869
879
  type ProfileLookupParams as ProfileLookupParams,
870
880
  };
871
881
 
882
+ export {
883
+ CreatorEmails as CreatorEmails,
884
+ type CreatorEmailLookupResponse as CreatorEmailLookupResponse,
885
+ type CreatorEmailLookupParams as CreatorEmailLookupParams,
886
+ };
887
+
872
888
  export {
873
889
  Posts as Posts,
874
890
  type PostListResponse as PostListResponse,
@@ -0,0 +1,195 @@
1
+ // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2
+
3
+ import { APIResource } from '../core/resource';
4
+ import { APIPromise } from '../core/api-promise';
5
+ import { RequestOptions } from '../internal/request-options';
6
+
7
+ /**
8
+ * Look up known creator email addresses by creator ID or social username. Empty or unresolved results are not billable.
9
+ */
10
+ export class CreatorEmails extends APIResource {
11
+ /**
12
+ * Look up known email addresses for creators by creator ID or social username.
13
+ *
14
+ * **Billing behavior:**
15
+ *
16
+ * - Charged only for unique resolved creators with at least one returned email
17
+ * - Empty and unresolved results are not billable
18
+ * - Returns validation status so unvalidated emails are explicit
19
+ *
20
+ * **Pricing**: 5 credits per creator with at least one returned email ($0.05)
21
+ */
22
+ lookup(body: CreatorEmailLookupParams, options?: RequestOptions): APIPromise<CreatorEmailLookupResponse> {
23
+ return this._client.post('/v1/creator-emails/lookup', { body, ...options });
24
+ }
25
+ }
26
+
27
+ /**
28
+ * Creator email lookup response
29
+ */
30
+ export interface CreatorEmailLookupResponse {
31
+ data: CreatorEmailLookupResponse.Data;
32
+ }
33
+
34
+ export namespace CreatorEmailLookupResponse {
35
+ export interface Data {
36
+ /**
37
+ * Creator email lookup billing summary
38
+ */
39
+ billing: Data.Billing;
40
+
41
+ results: Array<Data.Result>;
42
+ }
43
+
44
+ export namespace Data {
45
+ /**
46
+ * Creator email lookup billing summary
47
+ */
48
+ export interface Billing {
49
+ /**
50
+ * Unique resolved creators with at least one returned email
51
+ */
52
+ billable_results: number;
53
+
54
+ /**
55
+ * Preview of credits charged for this lookup
56
+ */
57
+ credits_charged: number;
58
+ }
59
+
60
+ /**
61
+ * Creator email lookup result
62
+ */
63
+ export interface Result {
64
+ /**
65
+ * Resolved creator ID, or null when the input could not be resolved
66
+ */
67
+ creator_id: string | null;
68
+
69
+ /**
70
+ * API-visible emails for the resolved creator. Empty results are not billable.
71
+ */
72
+ emails: Array<Result.Email>;
73
+
74
+ /**
75
+ * Creator email lookup input by creator ID or social handle
76
+ */
77
+ input: Result.CreatorEmailLookupByIDOutput | Result.CreatorEmailLookupByHandleOutput;
78
+
79
+ /**
80
+ * Whether the lookup resolved to a creator profile
81
+ */
82
+ resolved: boolean;
83
+ }
84
+
85
+ export namespace Result {
86
+ /**
87
+ * API-visible creator email
88
+ */
89
+ export interface Email {
90
+ /**
91
+ * Nullable confidence score for the email
92
+ */
93
+ confidence: number | null;
94
+
95
+ /**
96
+ * Email address as stored, preserving original casing
97
+ */
98
+ email: string;
99
+
100
+ /**
101
+ * When Influship first observed this email
102
+ */
103
+ first_seen_at: string;
104
+
105
+ /**
106
+ * Whether this is the primary email for the creator
107
+ */
108
+ is_primary: boolean;
109
+
110
+ /**
111
+ * When Influship most recently observed this email
112
+ */
113
+ last_seen_at: string;
114
+
115
+ /**
116
+ * API-visible email validation status
117
+ */
118
+ status: 'unvalidated' | 'valid' | 'risky' | 'creator_verified';
119
+
120
+ /**
121
+ * When the email was last validated, if known
122
+ */
123
+ validated_at: string | null;
124
+ }
125
+
126
+ /**
127
+ * Creator email lookup input by creator ID
128
+ */
129
+ export interface CreatorEmailLookupByIDOutput {
130
+ /**
131
+ * Creator profile ID to look up directly
132
+ */
133
+ creator_id: string;
134
+ }
135
+
136
+ /**
137
+ * Creator email lookup input by social handle
138
+ */
139
+ export interface CreatorEmailLookupByHandleOutput {
140
+ /**
141
+ * Social platform for handle-based lookup
142
+ */
143
+ platform: 'instagram';
144
+
145
+ /**
146
+ * Social username for handle-based lookup
147
+ */
148
+ username: string;
149
+ }
150
+ }
151
+ }
152
+ }
153
+
154
+ export interface CreatorEmailLookupParams {
155
+ /**
156
+ * Creator lookups to resolve. Response rows preserve this input order.
157
+ */
158
+ creators: Array<
159
+ CreatorEmailLookupParams.CreatorEmailLookupByID | CreatorEmailLookupParams.CreatorEmailLookupByHandle
160
+ >;
161
+ }
162
+
163
+ export namespace CreatorEmailLookupParams {
164
+ /**
165
+ * Creator email lookup input by creator ID
166
+ */
167
+ export interface CreatorEmailLookupByID {
168
+ /**
169
+ * Creator profile ID to look up directly
170
+ */
171
+ creator_id: string;
172
+ }
173
+
174
+ /**
175
+ * Creator email lookup input by social handle
176
+ */
177
+ export interface CreatorEmailLookupByHandle {
178
+ /**
179
+ * Social platform for handle-based lookup
180
+ */
181
+ platform: 'instagram';
182
+
183
+ /**
184
+ * Social username for handle-based lookup
185
+ */
186
+ username: string;
187
+ }
188
+ }
189
+
190
+ export declare namespace CreatorEmails {
191
+ export {
192
+ type CreatorEmailLookupResponse as CreatorEmailLookupResponse,
193
+ type CreatorEmailLookupParams as CreatorEmailLookupParams,
194
+ };
195
+ }
@@ -1,6 +1,11 @@
1
1
  // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2
2
 
3
3
  export * from './shared';
4
+ export {
5
+ CreatorEmails,
6
+ type CreatorEmailLookupResponse,
7
+ type CreatorEmailLookupParams,
8
+ } from './creator-emails';
4
9
  export {
5
10
  Creators,
6
11
  type CreatorRetrieveResponse,
@@ -125,24 +125,48 @@ export namespace PostListResponse {
125
125
  */
126
126
  export interface Media {
127
127
  /**
128
- * Video duration in seconds
128
+ * Per-item structure for carousel posts. Null for non-carousel posts. Per-item
129
+ * video_url is intentionally omitted (would be stale). For fresh video URLs, call
130
+ * GET /v1/raw/instagram/post/{shortcode}.
131
+ */
132
+ carousel_items: Array<Media.CarouselItem> | null;
133
+
134
+ /**
135
+ * Video duration in seconds. Null for non-video posts.
129
136
  */
130
137
  duration_seconds: number | null;
131
138
 
132
139
  /**
133
- * Thumbnail URL
140
+ * Thumbnail URL. For videos, this is the cover frame.
134
141
  */
135
142
  thumbnail_url: string | null;
136
143
 
137
144
  /**
138
- * Media URL
145
+ * Cover/primary image URL for image and carousel posts. Null for video posts —
146
+ * call GET /v1/raw/instagram/post/{shortcode} for a fresh, downloadable video URL.
147
+ * Note: returned image URLs are Instagram CDN URLs and may expire; a future change
148
+ * will migrate to persistent R2-hosted URLs.
139
149
  */
140
150
  url: string | null;
151
+ }
141
152
 
142
- /**
143
- * Video URL (for video content)
144
- */
145
- video_url: string | null;
153
+ export namespace Media {
154
+ export interface CarouselItem {
155
+ /**
156
+ * Zero-based position in the carousel.
157
+ */
158
+ index: number;
159
+
160
+ /**
161
+ * True if this item is a video.
162
+ */
163
+ is_video: boolean;
164
+
165
+ /**
166
+ * Thumbnail URL for this item. Cover frame for videos.
167
+ */
168
+ thumbnail_url: string | null;
169
+ }
146
170
  }
147
171
 
148
172
  /**
@@ -20,6 +20,10 @@ export class Instagram extends APIResource {
20
20
  * **Note:** These fields are only guaranteed on this raw single-post lookup.
21
21
  * Cached post-list endpoints may not include them.
22
22
  *
23
+ * Returns fresh `video_url` (single best stream) and `video_versions[]`
24
+ * (multi-bitrate). These are signed Instagram CDN URLs valid for ~24h — download
25
+ * promptly. For carousels with embedded videos, see `carousel_items[].video_url`.
26
+ *
23
27
  * **Pricing**: 1 credit per post scraped ($0.01)
24
28
  *
25
29
  * @example
@@ -40,6 +44,9 @@ export class Instagram extends APIResource {
40
44
  * **Note:** Batch post lookup is capped at 20 shortcodes per request and is
41
45
  * charged for every requested shortcode.
42
46
  *
47
+ * Returns fresh `video_url` and `video_versions[]` per post (signed IG CDN URLs,
48
+ * ~24h validity). Batch up to 20 posts at 1 credit ($0.01) each.
49
+ *
43
50
  * **Pricing**: 1 credit per post scraped ($0.01)
44
51
  *
45
52
  * @example
@@ -66,6 +73,10 @@ export class Instagram extends APIResource {
66
73
  * **Note:** Live scraping is slower than cached data (2-5 seconds) and costs more.
67
74
  * Use cached endpoints when freshness isn't critical.
68
75
  *
76
+ * The `posts[]` array returns up to 12 recent posts with fresh `video_url` for
77
+ * each video post. This is the cheapest bulk-download path: 0.5 credits ($0.005)
78
+ * per profile call vs 1 credit per individual raw-post call.
79
+ *
69
80
  * **Pricing**: 0.5 credits per profile scraped ($0.005)
70
81
  *
71
82
  * @example
@@ -274,8 +285,6 @@ export interface InstagramTranscriptResponse {
274
285
 
275
286
  language: string;
276
287
 
277
- post: InstagramTranscriptResponse.Post;
278
-
279
288
  scraped_at: string;
280
289
 
281
290
  shortcode: string;
@@ -285,6 +294,8 @@ export interface InstagramTranscriptResponse {
285
294
  word_count: number;
286
295
 
287
296
  duration_seconds?: number;
297
+
298
+ post?: InstagramTranscriptResponse.Post;
288
299
  }
289
300
 
290
301
  export namespace InstagramTranscriptResponse {
package/src/version.ts CHANGED
@@ -1 +1 @@
1
- export const VERSION = '0.10.2'; // x-release-please-version
1
+ export const VERSION = '0.12.0'; // x-release-please-version
package/version.d.mts CHANGED
@@ -1,2 +1,2 @@
1
- export declare const VERSION = "0.10.2";
1
+ export declare const VERSION = "0.12.0";
2
2
  //# sourceMappingURL=version.d.mts.map
package/version.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- export declare const VERSION = "0.10.2";
1
+ export declare const VERSION = "0.12.0";
2
2
  //# sourceMappingURL=version.d.ts.map
package/version.js CHANGED
@@ -1,5 +1,5 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.VERSION = void 0;
4
- exports.VERSION = '0.10.2'; // x-release-please-version
4
+ exports.VERSION = '0.12.0'; // x-release-please-version
5
5
  //# sourceMappingURL=version.js.map
package/version.mjs CHANGED
@@ -1,2 +1,2 @@
1
- export const VERSION = '0.10.2'; // x-release-please-version
1
+ export const VERSION = '0.12.0'; // x-release-please-version
2
2
  //# sourceMappingURL=version.mjs.map