@yume-chan/adb 0.0.10 → 0.0.13

package/CHANGELOG.json

@@ -1,6 +1,56 @@
 {
   "name": "@yume-chan/adb",
   "entries": [
+    {
+      "version": "0.0.13",
+      "tag": "@yume-chan/adb_v0.0.13",
+      "date": "Thu, 28 Apr 2022 01:23:53 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "Add support for raw shell mode"
+          },
+          {
+            "comment": "Add support for LIS2 command in Sync protocol"
+          },
+          {
+            "comment": "Add workaround for the push_mkdir issue in Android 9"
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.0.12",
+      "tag": "@yume-chan/adb_v0.0.12",
+      "date": "Sun, 03 Apr 2022 11:18:47 GMT",
+      "comments": {}
+    },
+    {
+      "version": "0.0.11",
+      "tag": "@yume-chan/adb_v0.0.11",
+      "date": "Sun, 03 Apr 2022 10:54:15 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "Add power related API"
+          },
+          {
+            "comment": "Update compatibility matrix"
+          },
+          {
+            "comment": "Update license year"
+          }
+        ],
+        "patch": [
+          {
+            "comment": "Update to use Web Streams API"
+          },
+          {
+            "comment": "Improve compatibility with Node.js 12 ESM format"
+          }
+        ]
+      }
+    },
     {
       "version": "0.0.10",
       "tag": "@yume-chan/adb_v0.0.10",

package/CHANGELOG.md

@@ -1,6 +1,34 @@
 # Change Log - @yume-chan/adb
 
-This log was last generated on Sun, 09 Jan 2022 15:52:20 GMT and should not be manually modified.
+This log was last generated on Thu, 28 Apr 2022 01:23:53 GMT and should not be manually modified.
+
+## 0.0.13
+Thu, 28 Apr 2022 01:23:53 GMT
+
+### Updates
+
+- Add support for raw shell mode
+- Add support for LIS2 command in Sync protocol
+- Add workaround for the push_mkdir issue in Android 9
+
+## 0.0.12
+Sun, 03 Apr 2022 11:18:47 GMT
+
+_Version update only_
+
+## 0.0.11
+Sun, 03 Apr 2022 10:54:15 GMT
+
+### Patches
+
+- Update to use Web Streams API
+- Improve compatibility with Node.js 12 ESM format
+
+### Updates
+
+- Add power related API
+- Update compatibility matrix
+- Update license year
 
 ## 0.0.10
 Sun, 09 Jan 2022 15:52:20 GMT

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Simon Chan
+Copyright (c) 2020-2022 Simon Chan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,21 +5,23 @@ TypeScript implementation of Android Debug Bridge (ADB) protocol.
 **WARNING:** The public API is UNSTABLE. If you have any questions, please open an issue.
 
 - [Compatibility](#compatibility)
+  - [Basic usage](#basic-usage)
+  - [Use without bundlers](#use-without-bundlers)
 - [Connection](#connection)
   - [Backend](#backend)
     - [`connect`](#connect)
-    - [`read`](#read)
-    - [`write`](#write)
 - [Authentication](#authentication)
     - [AdbCredentialStore](#adbcredentialstore)
       - [`generateKey`](#generatekey)
       - [`iterateKeys`](#iteratekeys)
       - [Implementations](#implementations)
     - [AdbAuthenticator](#adbauthenticator)
+    - [`authenticate`](#authenticate)
 - [Stream multiplex](#stream-multiplex)
-  - [Backend](#backend-1)
 - [Commands](#commands)
-  - [childProcess](#childprocess)
+  - [subprocess](#subprocess)
+    - [raw mode](#raw-mode)
+    - [pty mode](#pty-mode)
   - [usb](#usb)
   - [tcpip](#tcpip)
   - [sync](#sync)
@@ -36,50 +38,46 @@ TypeScript implementation of Android Debug Bridge (ADB) protocol.
 
 ## Compatibility
 
-The main limiting factor of compatibility is [@yume-chan/struct](https://www.npmjs.com/package/@yume-chan/struct).
+Here is a list of features, their used APIs, and their compatibilities. If an optional feature is not actually used, its requirements can be ignored.
 
-This library doesn't use any DOM or Node.js API.
+Some features can be polyfilled to support older runtimes, but this library doesn't ship with any polyfills.
 
-|                 | Chrome | Edge | Firefox | Internet Explorer | Safari         | Node.js |
-| --------------- | ------ | ---- | ------- | ----------------- | -------------- | ------- |
-| **Basic usage** | 68     | 79   | 68      | No                | 14<sup>1</sup> | 10.4    |
+Each backend may have different requirements.
 
-<sup>1</sup> Requires a polyfill for [`DataView#getBigUint64`][MDN_DataView_getBigUint64] and [`DataView#setBigUint64`][MDN_DataView_setBigUint64]
+### Basic usage
 
-[MDN_DataView_getBigUint64]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/getBigUint64
-[MDN_DataView_setBigUint64]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView/setBigUint64
+|                                 | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js             |
+| ------------------------------- | ------ | ---- | ------- | ----------------- | ------ | ------------------- |
+| `@yume-chan/struct`<sup>1</sup> | 67     | 79   | 68      | No                | 14     | 8.3<sup>2</sup>, 11 |
+| *Overall*                       | 67     | 79   | No      | No                | 14.1   | 16.5                |
+
+<sup>1</sup> `uint64` and `string` are used.
+
+<sup>2</sup> `TextEncoder` and `TextDecoder` are only available in `util` module. Need to be assigned to `globalThis`.
+
+### Use without bundlers
+
+|                 | Chrome | Edge | Firefox | Internet Explorer | Safari | Node.js |
+| --------------- | ------ | ---- | ------- | ----------------- | ------ | ------- |
+| Top-level await | 89     | 89   | 89      | No                | 15     | 14.8    |
 
 ## Connection
 
 This library doesn't tie to a specific transportation method.
 
-Instead, a `Backend` is responsible for transferring data in its own way (USB, WebSocket, etc).
+Instead, a `Backend` is responsible for transferring data in its own way (USB, WebSocket, TCP, etc).
 
 ### Backend
 
 #### `connect`
 
-Establishes a connection with the device.
-
-If a backend doesn't have extra steps to establish the connection, it can omit the `connect` method implementation.
-
-#### `read`
-
 ```ts
-read(length: number): ArrayBuffer | Promise<ArrayBuffer>
+connect(): ValueOrPromise<ReadableWritablePair<AdbPacketCore, AdbPacketInit>>
 ```
 
-Reads the specified amount of data from the underlying connection.
+Connect to a device and create a pair of `AdbPacket` streams.
 
-The returned `ArrayBuffer` may have more or less data than the `length` parameter specified, if there is some residual data in the connection buffer. The client will automatically call `read` again with the same `length`.
-
-#### `write`
-
-```ts
-write(buffer: ArrayBuffer): void | Promise<void>
-```
-
-Writes data to the underlying connection.
+The backend, instead of the core library, is responsible for serializing and deserializing the packets. Because it's extreme slow for WebUSB backend (`@yume-chan/adb-backend-webusb`) to read packets with unknown size.
 
 ## Authentication
 
@@ -87,22 +85,19 @@ For how does ADB authentication work, see https://chensi.moe/blog/2020/09/30/web
 
 In this library, authentication comes in two parts:
 
-* `AdbCredentialStore`: because JavaScript has no unified method to generate, store and iterate crypto keys, an implementation of `AdbCredentialStore` is required for the two built-in authenticators.
-* `AdbAuthenticator`: can be used to implement custom authentication modes.
-
-Custom `AdbCredentialStore`s and `AdbAuthenticator`s can be specified in the `Adb#connect` method.
-
 #### AdbCredentialStore
 
+An interface to generate, store and iterate ADB private keys on each runtime. (Because Node.js and Browsers have different APIs to do this)
+
 ##### `generateKey`
 
 ```ts
-generateKey(): ArrayBuffer | Promise<ArrayBuffer>
+generateKey(): ValueOrPromise<Uint8Array>
 ```
 
 Generate and store a RSA private key with modulus length `2048` and public exponent `65537`.
 
-The returned `ArrayBuffer` is the private key in PKCS #8 format.
+The returned `Uint8Array` is the private key in PKCS #8 format.
 
 ##### `iterateKeys`
 
@@ -116,7 +111,7 @@ Each call to `iterateKeys` must return a different iterator that iterate through
 
 ##### Implementations
 
-The `@yume-chan/adb-backend-webusb` package contains a `AdbWebCredentialStore` implementation using Web Crypto API to generating keys and Web Storage API to storing keys.
+The `@yume-chan/adb-credential-web` package contains a `AdbWebCredentialStore` implementation using Web Crypto API for generating keys and Web Storage API for storing keys.
 
 #### AdbAuthenticator
 
@@ -124,6 +119,20 @@ An `AdbAuthenticator` generates `AUTH` responses for each `AUTH` request from se
 
 This package contains `AdbSignatureAuthenticator` and `AdbPublicKeyAuthenticator`, the two basic modes.
 
+#### `authenticate`
+
+```ts
+static async authenticate(
+    connection: ReadableWritablePair<AdbPacketCore, AdbPacketCore>,
+    credentialStore: AdbCredentialStore,
+    authenticators = AdbDefaultAuthenticators,
+): Promise<Adb>
+```
+
+Call this method to authenticate the connection and create an `Adb` instance.
+
+If an authentication process failed, it's possible to call `authenticate` again on the same connection (`AdbPacket` stream pair). Every time the device receives a `CNXN` packet, it resets all internal state, and starts a new authentication process.
+
 ## Stream multiplex
 
 ADB commands are all based on streams. Multiple streams can send and receive at the same time in one connection.
@@ -133,25 +142,36 @@ ADB commands are all based on streams. Multiple streams can send and receive at
 3. Client and server read/write on the stream.
 4. Client/server sends a `CLSE` to close the stream.
 
-The `Backend` is responsible for reading and writing data from underlying source.
+## Commands
 
-### Backend
+### subprocess
 
-## Commands
+ADB has two subprocess invocation modes and two data protocols (4 combinations).
+
+#### raw mode
+
+In raw mode, Shell protocol transfers `stdout` and `stderr` separately. It also supports returning exit code.
+
+|                             | Legacy protocol             | Shell Protocol               |
+| --------------------------- | --------------------------- | ---------------------------- |
+| Feature flag                | -                           | `shell_v2`                   |
+| Implementation              | `AdbNoneSubprocessProtocol` | `AdbShellSubprocessProtocol` |
+| Splitting stdout and stderr | No                          | Yes                          |
+| Returning exit code         | No                          | Yes                          |
+
+Use `spawn` method to create a subprocess in raw mode.
 
-### childProcess
+#### pty mode
 
-Spawns child process on server. ADB has two shell modes:
+In PTY mode, the subprocess has a pseudo-terminal, so it can send special control sequences like clear screen and set cursor position. The two protocols both send data in `stdout`, but Shell Protocol also supports resizing the terminal from client.
 
-|                             | Legacy mode      | Shell Protocol     |
-| --------------------------- | ---------------- | ------------------ |
-| Feature flag                | -                | `shell_v2`         |
-| Implementation              | `AdbLegacyShell` | `AdbShellProtocol` |
-| Splitting stdout and stderr | No               | Yes                |
-| Returning exit code         | No               | Yes                |
-| Resizing window             | No               | Yes                |
+|                             | Legacy protocol             | Shell Protocol               |
+| --------------------------- | --------------------------- | ---------------------------- |
+| Feature flag                | -                           | `shell_v2`                   |
+| Implementation              | `AdbNoneSubprocessProtocol` | `AdbShellSubprocessProtocol` |
+| Resizing window             | No                          | Yes                          |
 
-The `Adb#childProcess#shell` and `Adb#childProcess#spawn` methods accepts a list of implementations, and will use the first supported one.
+Use `shell` method to create a subprocess in PTY mode.
 
 ### usb
 

package/esm/adb.d.ts

@@ -0,0 +1,48 @@
+import { type AdbCredentialStore } from './auth.js';
+import { AdbPower, AdbReverseCommand, AdbSubprocess, AdbSync, AdbTcpIpCommand, type AdbFrameBuffer } from './commands/index.js';
+import { AdbFeatures } from './features.js';
+import { type AdbPacketData, type AdbPacketInit } from './packet.js';
+import { type AdbSocket } from './socket/index.js';
+import { WritableStream, type ReadableWritablePair } from "./stream/index.js";
+export declare enum AdbPropKey {
+    Product = "ro.product.name",
+    Model = "ro.product.model",
+    Device = "ro.product.device",
+    Features = "features"
+}
+export declare const VERSION_OMIT_CHECKSUM = 16777217;
+export declare class Adb {
+    /**
+     * It's possible to call `authenticate` multiple times on a single connection,
+     * every time the device receives a `CNXN` packet, it resets its internal state,
+     * and starts a new authentication process.
+     */
+    static authenticate(connection: ReadableWritablePair<AdbPacketData, AdbPacketInit>, credentialStore: AdbCredentialStore, authenticators?: import("./auth.js").AdbAuthenticator[]): Promise<Adb>;
+    private readonly packetDispatcher;
+    get disconnected(): Promise<void>;
+    private _protocolVersion;
+    get protocolVersion(): number | undefined;
+    private _product;
+    get product(): string | undefined;
+    private _model;
+    get model(): string | undefined;
+    private _device;
+    get device(): string | undefined;
+    private _features;
+    get features(): AdbFeatures[] | undefined;
+    readonly subprocess: AdbSubprocess;
+    readonly power: AdbPower;
+    readonly reverse: AdbReverseCommand;
+    readonly tcpip: AdbTcpIpCommand;
+    constructor(connection: ReadableWritablePair<AdbPacketData, AdbPacketInit>, version: number, maxPayloadSize: number, banner: string);
+    private parseBanner;
+    createSocket(service: string): Promise<AdbSocket>;
+    createSocketAndWait(service: string): Promise<string>;
+    getProp(key: string): Promise<string>;
+    rm(...filenames: string[]): Promise<string>;
+    install(): WritableStream<Uint8Array>;
+    sync(): Promise<AdbSync>;
+    framebuffer(): Promise<AdbFrameBuffer>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=adb.d.ts.map

package/esm/adb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adb.d.ts","sourceRoot":"","sources":["../src/adb.ts"],"names":[],"mappings":"AAGA,OAAO,EAA0D,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC5G,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,EAAmC,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACjK,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAiC,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAAyD,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGrI,oBAAY,UAAU;IAClB,OAAO,oBAAoB;IAC3B,KAAK,qBAAqB;IAC1B,MAAM,sBAAsB;IAC5B,QAAQ,aAAa;CACxB;AAED,eAAO,MAAM,qBAAqB,WAAa,CAAC;AAEhD,qBAAa,GAAG;IACZ;;;;OAIG;WACiB,YAAY,CAC5B,UAAU,EAAE,oBAAoB,CAAC,aAAa,EAAE,aAAa,CAAC,EAC9D,eAAe,EAAE,kBAAkB,EACnC,cAAc,yCAA6B,GAC5C,OAAO,CAAC,GAAG,CAAC;IAsGf,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsB;IAEvD,IAAW,YAAY,kBAAiD;IAExE,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,IAAW,eAAe,uBAAoC;IAE9D,OAAO,CAAC,QAAQ,CAAqB;IACrC,IAAW,OAAO,uBAA4B;IAE9C,OAAO,CAAC,MAAM,CAAqB;IACnC,IAAW,KAAK,uBAA0B;IAE1C,OAAO,CAAC,OAAO,CAAqB;IACpC,IAAW,MAAM,uBAA2B;IAE5C,OAAO,CAAC,SAAS,CAA4B;IAC7C,IAAW,QAAQ,8BAA6B;IAEhD,SAAgB,UAAU,EAAE,aAAa,CAAC;IAC1C,SAAgB,KAAK,EAAE,QAAQ,CAAC;IAChC,SAAgB,OAAO,EAAE,iBAAiB,CAAC;IAC3C,SAAgB,KAAK,EAAE,eAAe,CAAC;gBAGnC,UAAU,EAAE,oBAAoB,CAAC,aAAa,EAAE,aAAa,CAAC,EAC9D,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM;IA+BlB,OAAO,CAAC,WAAW;IAmCN,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAIjD,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASrD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOrC,EAAE,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAOjD,OAAO;IAID,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAKxB,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC;IAItC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAGxC"}