phonesinc 2.2.0 → 2.3.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/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { VirtualPhone, VirtualPhoneHost, VirtualPhoneTarget, ApiResponse, App, AppiumRequest, AppRequest, AuthenticatorAddRequest, AuthenticatorCode, AuthenticatorEntry, AuthenticatorUpdateRequest, Screen, ScreenCreateRequest, ScreenUpdateRequest, Workflow, WorkflowCreateRequest, WorkflowRun, WorkflowRunRequest, WorkflowRunSummary, WorkflowSummary, WorkflowUpdateRequest, ClientOptions, Endpoint, FileExport, Identity, KeyRequest, Media, MediaImported, MediaImportFailed, MediaImporting, MediaImportStatusRequest, MediaSource, MediaUploadRequest, OptionalEndpoint, Phone, PhoneFile, PhoneResult, PhoneListRequest, PhoneSelection, PhoneTargets, Rental, RentRequest, RequestOptions, ScreenRequest, Screenshot, Session, Stream, TouchRequest, TypeRequest, VerificationService } from "./types.js";
1
+ import type { VirtualPhone, VirtualPhoneHost, VirtualPhoneTarget, ApiResponse, App, AppiumRequest, AppRequest, AuthenticatorAddRequest, AuthenticatorScanRequest, AuthenticatorCode, AuthenticatorEntry, AuthenticatorUpdateRequest, Screen, ScreenCreateRequest, ScreenUpdateRequest, Workflow, WorkflowCreateRequest, WorkflowNodeType, WorkflowRun, WorkflowRunRequest, WorkflowRunSummary, WorkflowSummary, WorkflowUpdateRequest, ClientOptions, Endpoint, FileExport, Identity, KeyRequest, Media, MediaImported, MediaImportFailed, MediaImporting, MediaImportStatusRequest, MediaSource, MediaUploadRequest, OptionalEndpoint, Phone, PhoneFile, PhoneResult, PhoneListRequest, PhoneSelection, PhoneTargets, Rental, RentRequest, RequestOptions, ScreenRequest, Screenshot, Session, Stream, ApiSchema, CommitRequest, Committed, PhoneState, AppLaunchRequest, Observed, SessionWait, SwipeRequest, Waited, WaitRequest, TapRequest, Tapped, TouchRequest, TypeRequest, VerificationService } from "./types.js";
2
2
  export type * from "./types.js";
3
3
  /** Public phone operations. A request is sent once; actions are never replayed. */
4
4
  export declare class PhonesInc {
@@ -35,16 +35,21 @@ export declare class PhonesInc {
35
35
  stop: Endpoint<VirtualPhoneTarget, VirtualPhone>;
36
36
  };
37
37
  readonly me: OptionalEndpoint<Record<never, never>, Identity>;
38
+ /** Every key, node type, screen condition, target and enum the API takes (T-0650). */
39
+ readonly schema: OptionalEndpoint<Record<never, never>, ApiSchema>;
38
40
  readonly phones: {
39
41
  get: OptionalEndpoint<PhoneListRequest, Phone[]>;
40
42
  reboot: Endpoint<PhoneTargets, PhoneResult[]>;
43
+ /** Foreground app, screen, lock and network without a screenshot (T-0650). */
44
+ state: OptionalEndpoint<PhoneSelection, PhoneResult<PhoneState>[]>;
41
45
  };
42
46
  readonly session: {
43
- get: OptionalEndpoint<PhoneSelection, Session[]>;
44
- start: OptionalEndpoint<PhoneSelection & {
47
+ get: OptionalEndpoint<PhoneSelection & SessionWait, Session[]>;
48
+ start: OptionalEndpoint<PhoneSelection & SessionWait & {
45
49
  viewId?: string;
46
50
  }, PhoneResult<{
47
51
  session: Session;
52
+ timedOut?: true;
48
53
  }>[]>;
49
54
  renew: OptionalEndpoint<PhoneSelection, PhoneResult<{
50
55
  session: Session;
@@ -64,16 +69,40 @@ export declare class PhonesInc {
64
69
  };
65
70
  };
66
71
  };
67
- readonly touch: Endpoint<TouchRequest, PhoneResult[]>;
68
- readonly type: Endpoint<TypeRequest, PhoneResult[]>;
69
- readonly key: Endpoint<KeyRequest, PhoneResult[]>;
72
+ readonly touch: Endpoint<TouchRequest, PhoneResult<Observed>[]>;
73
+ readonly type: Endpoint<TypeRequest, PhoneResult<Observed>[]>;
74
+ readonly key: Endpoint<KeyRequest, PhoneResult<Observed>[]>;
75
+ /** Tap by text, detector label, element id or point (T-0650). */
76
+ readonly tap: Endpoint<TapRequest, PhoneResult<Observed & {
77
+ tapped: Tapped;
78
+ }>[]>;
79
+ /** The one tap of an irreversible action, at most once per kind and key (T-0650). */
80
+ readonly commit: Endpoint<CommitRequest, PhoneResult<Observed & Committed>[]>;
81
+ /** Wait until text shows or goes, an element shows, the screen is still or an app is in front. */
82
+ readonly wait: Endpoint<WaitRequest, PhoneResult<Waited>[]>;
83
+ readonly swipe: Endpoint<SwipeRequest, PhoneResult<Observed & {
84
+ swiped: {
85
+ from: {
86
+ x: number;
87
+ y: number;
88
+ };
89
+ to: {
90
+ x: number;
91
+ y: number;
92
+ };
93
+ count: number;
94
+ };
95
+ }>[]>;
70
96
  readonly screen: OptionalEndpoint<ScreenRequest, PhoneResult<Screenshot>[]>;
71
97
  readonly apps: {
72
98
  get: OptionalEndpoint<PhoneSelection, PhoneResult<{
73
99
  apps: App[];
74
100
  }>[]>;
75
- launch: Endpoint<AppRequest, PhoneResult[]>;
76
- stop: Endpoint<AppRequest, PhoneResult[]>;
101
+ launch: Endpoint<AppLaunchRequest, PhoneResult<Observed & {
102
+ foregroundApp?: string | null;
103
+ timedOut?: true;
104
+ }>[]>;
105
+ stop: Endpoint<AppRequest, PhoneResult<Observed>[]>;
77
106
  uninstall: Endpoint<AppRequest, PhoneResult[]>;
78
107
  install: Endpoint<PhoneTargets & MediaSource, PhoneResult<{
79
108
  app: App;
@@ -137,6 +166,10 @@ export declare class PhonesInc {
137
166
  phone?: string;
138
167
  }, AuthenticatorEntry[]>;
139
168
  add: Endpoint<AuthenticatorAddRequest, AuthenticatorEntry>;
169
+ /** Read the 2FA QR code on a phone's screen (needs a session) and store it; the setup key is never answered. */
170
+ scan: Endpoint<AuthenticatorScanRequest, PhoneResult<{
171
+ entry: AuthenticatorEntry;
172
+ }>[]>;
140
173
  code: Endpoint<{
141
174
  id: string;
142
175
  }, AuthenticatorCode>;
@@ -164,6 +197,7 @@ export declare class PhonesInc {
164
197
  /** The organization's workflows: node graphs that drive phones, and their runs. */
165
198
  readonly workflows: {
166
199
  list: OptionalEndpoint<Record<never, never>, WorkflowSummary[]>;
200
+ nodeTypes: OptionalEndpoint<Record<never, never>, WorkflowNodeType[]>;
167
201
  get: Endpoint<{
168
202
  id: string;
169
203
  }, Workflow>;
package/dist/index.js CHANGED
@@ -97,9 +97,13 @@ export class PhonesInc {
97
97
  stop: this.required("/v1/virtual-phones/stop"),
98
98
  };
99
99
  me = this.optional("/v1/me");
100
+ /** Every key, node type, screen condition, target and enum the API takes (T-0650). */
101
+ schema = this.optional("/v1/schema");
100
102
  phones = {
101
103
  get: this.optional("/v1/phones"),
102
104
  reboot: this.required("/v1/phones/reboot"),
105
+ /** Foreground app, screen, lock and network without a screenshot (T-0650). */
106
+ state: this.optional("/v1/phone/state"),
103
107
  };
104
108
  session = {
105
109
  get: this.optional("/v1/session"),
@@ -138,6 +142,13 @@ export class PhonesInc {
138
142
  touch = this.required("/v1/touch");
139
143
  type = this.required("/v1/type");
140
144
  key = this.required("/v1/key");
145
+ /** Tap by text, detector label, element id or point (T-0650). */
146
+ tap = this.required("/v1/tap");
147
+ /** The one tap of an irreversible action, at most once per kind and key (T-0650). */
148
+ commit = this.required("/v1/commit");
149
+ /** Wait until text shows or goes, an element shows, the screen is still or an app is in front. */
150
+ wait = this.required("/v1/wait");
151
+ swipe = this.required("/v1/swipe");
141
152
  screen = this.optional("/v1/screen");
142
153
  apps = {
143
154
  get: this.optional("/v1/apps"),
@@ -195,6 +206,8 @@ export class PhonesInc {
195
206
  authenticator = {
196
207
  get: this.optional("/v1/authenticator"),
197
208
  add: this.required("/v1/authenticator/add"),
209
+ /** Read the 2FA QR code on a phone's screen (needs a session) and store it; the setup key is never answered. */
210
+ scan: this.required("/v1/authenticator/scan"),
198
211
  code: this.required("/v1/authenticator/code"),
199
212
  update: this.required("/v1/authenticator/update"),
200
213
  delete: this.required("/v1/authenticator/delete"),
@@ -210,6 +223,7 @@ export class PhonesInc {
210
223
  /** The organization's workflows: node graphs that drive phones, and their runs. */
211
224
  workflows = {
212
225
  list: this.optional("/v1/workflows"),
226
+ nodeTypes: this.optional("/v1/workflows/node-types"),
213
227
  get: this.required("/v1/workflows/get"),
214
228
  create: this.required("/v1/workflows/create"),
215
229
  update: this.required("/v1/workflows/update"),
package/dist/types.d.ts CHANGED
@@ -2,6 +2,16 @@
2
2
  export type ApiError = {
3
3
  code: string;
4
4
  message: string;
5
+ /** A refused name or value: the ones that are taken. */
6
+ allowed?: string[];
7
+ /** `target_not_found`: the closest things on the screen. */
8
+ candidates?: {
9
+ text?: string;
10
+ label?: string;
11
+ id?: number;
12
+ cx: number;
13
+ cy: number;
14
+ }[];
5
15
  };
6
16
  export type ApiResponse<T> = {
7
17
  ok: true;
@@ -22,6 +32,8 @@ export type Session = {
22
32
  id: string;
23
33
  phoneId: string;
24
34
  network: "connecting" | "ready" | "failed";
35
+ /** With `network: "failed"`: why, as a short code. */
36
+ reason?: string;
25
37
  startedAt: string;
26
38
  expiresAt: string;
27
39
  };
@@ -83,6 +95,12 @@ export type AuthenticatorAddRequest = {
83
95
  secret: string;
84
96
  phone?: string;
85
97
  };
98
+ /** One phone whose screen shows the 2FA QR code; the hub reads it and stores the entry for that phone. */
99
+ export type AuthenticatorScanRequest = {
100
+ phoneIds: [string];
101
+ app: AuthenticatorApp;
102
+ label: string;
103
+ };
86
104
  /** `phone: null` unlinks the phone. */
87
105
  export type AuthenticatorUpdateRequest = {
88
106
  id: string;
@@ -116,15 +134,95 @@ export type Element = Box & {
116
134
  label: string;
117
135
  confidence: number;
118
136
  };
137
+ /** `[id, "text" or "label", cx, cy, w, h]`: a compact text line or element. */
138
+ export type CompactRow = [number, string, number, number, number, number];
119
139
  export type Screenshot = {
120
- imageUrl: string;
121
- format: "png" | "jpeg";
122
- width: number;
123
- height: number;
124
- text?: TextLine[];
125
- elements?: Element[];
140
+ screenHash: string;
141
+ changed?: boolean;
142
+ imageUrl?: string;
143
+ format?: "png" | "jpeg";
144
+ width?: number;
145
+ height?: number;
146
+ scale?: number;
147
+ imageWidth?: number;
148
+ imageHeight?: number;
149
+ crop?: {
150
+ x: number;
151
+ y: number;
152
+ width: number;
153
+ height: number;
154
+ };
155
+ text?: TextLine[] | CompactRow[];
156
+ elements?: Element[] | CompactRow[];
126
157
  annotatedImageUrl?: string;
127
158
  };
159
+ /** `[x0, y0, x1, y1]`: left, top, right, bottom as fractions 0..1 of the screen. */
160
+ export type Region = [number, number, number, number];
161
+ export type ScreenView = "image" | "text" | "both";
162
+ export type LookOptions = {
163
+ view?: ScreenView;
164
+ format?: "png" | "jpeg";
165
+ quality?: number;
166
+ ocr?: boolean;
167
+ detect?: boolean;
168
+ annotate?: boolean;
169
+ compact?: boolean;
170
+ maxSide?: number;
171
+ region?: Region;
172
+ };
173
+ /** Look at the screen after an action, in the same answer. */
174
+ export type Observe = LookOptions & {
175
+ settleMs?: number;
176
+ };
177
+ export type Effect = {
178
+ screenChanged: boolean | null;
179
+ foregroundApp: string | null;
180
+ settled: boolean;
181
+ };
182
+ /** What an input endpoint adds with `observe`. */
183
+ export type Observed = {
184
+ screen?: Screenshot;
185
+ effect?: Effect;
186
+ warnings?: "no_effect"[];
187
+ };
188
+ /** What to tap: exactly one of text, label, element (with the screenHash it was read on) or a point. */
189
+ export type TapTarget = {
190
+ text: string;
191
+ exact?: boolean;
192
+ region?: Region;
193
+ nth?: number;
194
+ } | {
195
+ label: string;
196
+ region?: Region;
197
+ nth?: number;
198
+ } | {
199
+ element: number;
200
+ from: string;
201
+ } | {
202
+ x: number;
203
+ y: number;
204
+ };
205
+ export type Tapped = {
206
+ text?: string;
207
+ label?: string;
208
+ id?: number;
209
+ cx: number;
210
+ cy: number;
211
+ };
212
+ export type SwipePoint = [number, number] | {
213
+ x: number;
214
+ y: number;
215
+ };
216
+ export type SwipeRequest = PhoneTargets & {
217
+ direction?: "up" | "down" | "left" | "right";
218
+ distance?: number;
219
+ from?: SwipePoint;
220
+ to?: SwipePoint;
221
+ durationMs?: number;
222
+ count?: number;
223
+ gapMs?: number;
224
+ observe?: Observe;
225
+ };
128
226
  /** A service you can rent an email address or phone number for. */
129
227
  export type VerificationService = {
130
228
  id: string;
@@ -180,23 +278,26 @@ export type TouchPoint = {
180
278
  };
181
279
  export type TouchRequest = PhoneTargets & {
182
280
  inputs: TouchPoint[];
281
+ observe?: Observe;
282
+ };
283
+ export type TapRequest = PhoneTargets & {
284
+ target: TapTarget;
285
+ observe?: Observe;
183
286
  };
184
287
  export type TypeRequest = PhoneTargets & {
185
288
  text: string;
186
289
  duration?: number;
290
+ observe?: Observe;
187
291
  };
188
292
  export type Modifier = "shift" | "ctrl" | "alt" | "meta";
189
293
  export type Key = "home" | "enter" | "backspace" | "lock" | "unlock" | "back" | "app_switcher" | "volume_up" | "volume_down" | "tab" | "escape" | "delete" | "up" | "down" | "left" | "right" | "a" | "c" | "x" | "z" | "cursor_home" | "cursor_end" | "page_up" | "page_down" | "caps_lock";
190
294
  export type KeyRequest = PhoneTargets & {
191
295
  key: Key;
192
296
  modifiers?: Modifier[];
297
+ observe?: Observe;
193
298
  };
194
- export type ScreenRequest = PhoneSelection & {
195
- format?: "png" | "jpeg";
196
- quality?: number;
197
- ocr?: boolean;
198
- detect?: boolean;
199
- annotate?: boolean;
299
+ export type ScreenRequest = PhoneSelection & LookOptions & {
300
+ since?: string;
200
301
  };
201
302
  /** Exactly one existing library item or customer URL supplies the bytes. */
202
303
  export type MediaSource = {
@@ -242,6 +343,44 @@ export type MediaImportStatusRequest = PhoneTargets & ({
242
343
  });
243
344
  export type AppRequest = PhoneTargets & {
244
345
  appId: string;
346
+ observe?: Observe;
347
+ };
348
+ export type AppLaunchRequest = AppRequest & {
349
+ wait?: boolean;
350
+ waitSeconds?: number;
351
+ };
352
+ /** Wait for the network of a session to be ready (or failed). */
353
+ export type SessionWait = {
354
+ wait?: boolean;
355
+ waitSeconds?: number;
356
+ };
357
+ export type WaitUntil = {
358
+ text: string;
359
+ exact?: boolean;
360
+ region?: Region;
361
+ } | {
362
+ textGone: string;
363
+ exact?: boolean;
364
+ region?: Region;
365
+ } | {
366
+ label: string;
367
+ region?: Region;
368
+ } | {
369
+ stable: true;
370
+ } | {
371
+ app: string;
372
+ };
373
+ export type WaitRequest = PhoneTargets & {
374
+ until: WaitUntil;
375
+ timeoutSeconds?: number;
376
+ observe?: Observe;
377
+ };
378
+ export type Waited = {
379
+ met: boolean;
380
+ waitedMs: number;
381
+ found?: Tapped;
382
+ foregroundApp?: string | null;
383
+ screen?: Screenshot;
245
384
  };
246
385
  export type MediaUploadRequest = {
247
386
  file: Blob;
@@ -364,6 +503,27 @@ export type Workflow = {
364
503
  export type WorkflowSummary = Omit<Workflow, "nodes" | "issues"> & {
365
504
  nodeCount: number;
366
505
  };
506
+ /** A port of a node type: what an edge carries in or out. */
507
+ export type WorkflowNodePort = {
508
+ id: string;
509
+ type: string | string[];
510
+ isArray: boolean;
511
+ required: boolean;
512
+ };
513
+ /** A node type a workflow may use: its guide, its default `config` and its ports with that config. */
514
+ export type WorkflowNodeType = {
515
+ type: string;
516
+ label: string;
517
+ category: string;
518
+ description: string;
519
+ guide: string | null;
520
+ flowControl: boolean;
521
+ config: {
522
+ [key: string]: JsonValue;
523
+ };
524
+ inputs: WorkflowNodePort[];
525
+ outputs: WorkflowNodePort[];
526
+ };
367
527
  /** `nodes` is the graph as JSON text (a WorkflowNode array). */
368
528
  export type WorkflowCreateRequest = {
369
529
  name: string;
@@ -454,3 +614,73 @@ export type ScreenCreateRequest = {
454
614
  export type ScreenUpdateRequest = Partial<ScreenCreateRequest> & {
455
615
  id: string;
456
616
  };
617
+ /** What `/v1/schema` answers: JSON Schemas are plain JSON objects. */
618
+ export type ApiSchema = {
619
+ keys: string[];
620
+ modifiers: string[];
621
+ nodeTypes: {
622
+ type: string;
623
+ label: string;
624
+ category: string;
625
+ description: string;
626
+ guide: string | null;
627
+ flowControl: boolean;
628
+ config: Record<string, unknown>;
629
+ defaults: Record<string, unknown>;
630
+ inputs: {
631
+ id: string;
632
+ type: string | string[];
633
+ isArray: boolean;
634
+ required: boolean;
635
+ }[];
636
+ outputs: {
637
+ id: string;
638
+ type: string | string[];
639
+ isArray: boolean;
640
+ required: boolean;
641
+ }[];
642
+ }[];
643
+ screenConditions: Record<string, unknown>;
644
+ regionFormat: string;
645
+ targets: Record<string, unknown>;
646
+ waitConditions: Record<string, unknown>;
647
+ observe: Record<string, unknown>;
648
+ directions: string[];
649
+ views: string[];
650
+ formats: string[];
651
+ warnings: string[];
652
+ };
653
+ /** `/v1/phone/state`: what the phone can report without a screenshot; `null` where it cannot say. */
654
+ export type PhoneState = {
655
+ foregroundApp: string | null;
656
+ locked: boolean | null;
657
+ keyboardShown: boolean | null;
658
+ screenOn: boolean | null;
659
+ network: Session["network"] | null;
660
+ screen: {
661
+ width: number;
662
+ height: number;
663
+ } | null;
664
+ session: Session | null;
665
+ };
666
+ export type CommitKind = "post" | "like" | "follow" | "comment" | "delete" | "send" | "other";
667
+ export type CommitRequest = (PhoneTargets | {
668
+ phoneId: string;
669
+ }) & {
670
+ kind: CommitKind;
671
+ target: TapTarget;
672
+ idempotencyKey: string;
673
+ observe?: Observe;
674
+ };
675
+ export type Committed = {
676
+ receipt: {
677
+ kind: string;
678
+ idempotencyKey: string;
679
+ status: "intent" | "tapped" | "unknown";
680
+ madeBy: string;
681
+ createdAt: string;
682
+ updatedAt: string;
683
+ };
684
+ repeated: boolean;
685
+ tapped?: Tapped;
686
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "phonesinc",
3
- "version": "2.2.0",
3
+ "version": "2.3.0",
4
4
  "description": "The public Phones Inc API client",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",