@nonstrict/recordkit 0.2.1 → 0.3.0-alpha.2

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,23 +1,20 @@
 {
   "name": "@nonstrict/recordkit",
-  "version": "0.2.1",
+  "version": "0.3.0-alpha.2",
   "description": "RecordKit gives you hassle-free recording in Electron apps on macOS.",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "out/index.js",
+  "types": "out/index.d.ts",
   "exports": {
-    "import": "./dist/index.js",
-    "require": "./dist/index.cjs"
+    "import": "./out/index.js",
+    "require": "./out/index.cjs"
   },
-  "files": [
-    "dist"
-  ],
   "engines": {
     "node": ">=18.16"
   },
   "scripts": {
     "test": "jest",
-    "build": "rm -rf dist && tsc && rollup -c",
+    "build": "rm -rf out && tsc && rollup -c",
     "prepublish": "npm run build"
   },
   "keywords": [
@@ -34,7 +31,7 @@
   "author": {
     "name": "Nonstrict B.V.",
     "email": "team+recordkit@nonstrict.com",
-    "url": "https://nonstrict.eu"
+    "url": "https://nonstrict.eu/recordkit"
   },
   "license": "SEE LICENSE IN License.md",
   "devDependencies": {
@@ -43,6 +40,7 @@
     "jest": "^29.7.0",
     "rollup": "^4.12.0",
     "ts-jest": "^29.1.2",
+    "typedoc": "^0.25.11",
     "typescript": "^5.3.3"
   },
   "volta": {

package/rollup.config.js

@@ -0,0 +1,11 @@
+export default {
+  input: 'out/index.js',
+  output: [
+    {
+      file: 'out/index.cjs',
+      format: 'cjs',
+      sourcemap: true,
+    }
+  ],
+  external: ['node:child_process', 'node:fs', 'readline', 'crypto', 'stream']
+};

package/src/IpcRecordKit.ts

@@ -0,0 +1,36 @@
+import { ChildProcess, spawn } from 'node:child_process';
+import * as readline from 'readline';
+import { NSRPC } from "./NonstrictRPC.js";
+
+export class IpcRecordKit {
+  private childProcess?: ChildProcess;
+  readonly nsrpc: NSRPC;
+
+  constructor() {
+    this.nsrpc = new NSRPC((message) => this.write(message));
+  }
+
+  async initialize(recordKitRpcPath: string, logMessages: boolean = false): Promise<void> {
+    if (this.childProcess !== undefined) { throw new Error('RecordKit RPC: Already initialized.') }
+
+    this.nsrpc.logMessages = logMessages;
+    this.childProcess = await new Promise<ChildProcess>((resolve, reject) => {
+      const childProcess = spawn(recordKitRpcPath)
+      childProcess.on('spawn', () => { resolve(childProcess) })
+      childProcess.on('error', (error) => { reject(error) })
+    })
+
+    const { stdout } = this.childProcess
+    if (!stdout) { throw new Error('RecordKit RPC: No stdout stream on child process.') }
+
+    readline.createInterface({ input: stdout }).on('line', (line) => {
+      this.nsrpc.receive(line);
+    });
+  }
+
+  private write(message: String) {
+    const stdin = this.childProcess?.stdin;
+    if (!stdin) { throw new Error('RecordKit RPC: Missing stdin stream.') }
+    stdin.write(message + "\n")
+  }
+}

package/src/NonstrictRPC.test.ts

@@ -0,0 +1,98 @@
+import { NSRPC, NSRPCPerformClosureRequest } from './NonstrictRPC.js';
+import v8 from 'v8';
+
+// const finalizationRegistry = new FinalizationRegistry(async (destructor) => { console.log('==> ', destructor) })
+
+// finalizationRegistry.register({}, 'CHECK');
+// eval('%CollectGarbage(true)');
+
+describe('NonstrictRPC', () => {
+    it('needs tests', () => { });
+
+//     beforeAll(() => {
+//         v8.setFlagsFromString('--allow-natives-syntax');
+//     });
+
+//     describe('initialize', () => {
+//         it('sends init request w/parameters', (done) => {
+//             const rpc = new NSRPC((data) => {
+//                 const message = JSON.parse(data)
+//                 expect(message).toMatchSnapshot({ id: expect.any(String) });
+//                 done()
+//             });
+
+//             rpc.initialize({
+//                 target: 'TheTarget',
+//                 type: 'TheType',
+//                 params: { aParameter: 'TheValue' },
+//                 lifecycle: {}
+//             });
+//         });
+
+//         it('sends init request w/o parameters', (done) => {
+//             const rpc = new NSRPC((data) => {
+//                 const message = JSON.parse(data)
+//                 expect(message).toMatchSnapshot({ id: expect.any(String) });
+//                 done()
+//             });
+
+//             rpc.initialize({
+//                 target: 'TheTarget',
+//                 type: 'TheType',
+//                 lifecycle: {}
+//             });
+//         });
+
+//         it('sends release request', async () => {
+//             const rpc = new NSRPC((data) => {
+//                 const message = JSON.parse(data)
+//                 console.log(message)
+//                 // if (message.procedure === 'release') {
+//                 //     expect(message).toMatchSnapshot({ id: expect.any(String) });
+//                 //     done()
+//                 // }
+//             });
+
+//             async function scope() {
+//                 const foo = {}
+//                await rpc.initialize({
+//                     target: 'TheTarget',
+//                     type: 'TheType',
+//                     lifecycle: foo   
+//                 }); 
+//                 finalizationRegistry.register(foo, 'CHECK');
+//             }
+
+//             await scope();
+//             eval("%CollectGarbage(true)");
+//         });
+//     });
+
+//     describe('registerClosure', () => {
+//         it('should do something', (done) => {
+//             const rpc = new NSRPC((data) => {
+//                 expect(JSON.parse(data)).toStrictEqual({status:200,result:{test:"test"},nsrpc:1,id:"req_id"})
+//                 done()
+//             });
+
+//             const target = rpc.registerClosure({
+//                 handler: (params) => { params },
+//                 prefix: 'test',
+//                 lifecycle: {}
+//             });
+
+//             const rpcMessage: NSRPCPerformClosureRequest = {
+//                 nsrpc: 1,
+//                 id: 'req_id',
+//                 procedure: 'perform',
+//                 target,
+//                 params: { test: 'test' }
+//             }
+//             rpc.receive(JSON.stringify(rpcMessage));
+//         });x
+//     });
+
+//     function timeout(ms: number) {
+//         return new Promise<void>(resolve => setTimeout(resolve, ms));
+//       }
+});

package/src/NonstrictRPC.ts

@@ -0,0 +1,324 @@
+import { randomUUID } from "crypto";
+import { finalizationRegistry } from "./finalizationRegistry.js";
+
+type NSRPCMessage = NSRPCRequest | NSRPCResponse;
+
+/* Request types */
+
+type NSRPCRequest =
+  | NSRPCInitializationRequest
+  | NSRPCPerformStaticMethodRequest
+  | NSRPCPerformMethodRequest
+  | NSRPCPerformClosureRequest
+  | NSRPCReleaseRequest;
+
+interface NSRPCInitializationRequest {
+  nsrpc: number;
+  id: string;
+  procedure: "init";
+  target: string;
+  type: string;
+  params?: Record<string, unknown>;
+}
+
+interface NSRPCPerformStaticMethodRequest {
+  nsrpc: number;
+  id?: string;
+  procedure: "perform";
+  type: string;
+  action: string;
+  params?: Record<string, unknown>;
+}
+
+interface NSRPCPerformMethodRequest {
+  nsrpc: number;
+  id?: string;
+  procedure: "perform";
+  target: string;
+  action: string;
+  params?: Record<string, unknown>;
+}
+
+export interface NSRPCPerformClosureRequest {
+  nsrpc: number;
+  id?: string;
+  procedure: "perform";
+  target: string;
+  params?: Record<string, unknown>;
+}
+
+interface NSRPCReleaseRequest {
+  nsrpc: number;
+  id: string;
+  procedure: "release";
+  target: string;
+}
+
+type NSRPCRequestBody =
+  | NSRPCInitializationRequestBody
+  | NSRPCPerformStaticMethodRequestBody
+  | NSRPCPerformMethodRequestBody
+  | NSRPCPerformClosureRequestBody
+  | NSRPCReleaseRequestBody;
+type NSRPCInitializationRequestBody = Omit<
+  NSRPCInitializationRequest,
+  "nsrpc" | "id"
+>;
+type NSRPCPerformMethodRequestBody = Omit<
+  NSRPCPerformMethodRequest,
+  "nsrpc" | "id"
+>;
+type NSRPCPerformStaticMethodRequestBody = Omit<
+  NSRPCPerformStaticMethodRequest,
+  "nsrpc" | "id"
+>;
+type NSRPCPerformClosureRequestBody = Omit<
+  NSRPCPerformClosureRequest,
+  "nsrpc" | "id"
+>;
+type NSRPCReleaseRequestBody = Omit<NSRPCReleaseRequest, "nsrpc" | "id">;
+
+/* Response types */
+
+type NSRPCResponse = NSRPCSuccesfulResponse | NSRPCErrorResponse;
+
+interface NSRPCSuccesfulResponse {
+  nsrpc: number;
+  id: string;
+  status: 200;
+  result?: unknown;
+}
+
+interface NSRPCErrorResponse {
+  nsrpc: number;
+  id: string;
+  status: Exclude<number, 200>;
+  error: Record<string, unknown>;
+}
+
+type NSRPCResponseBody = NSRPCSuccesfulResponseBody | NSRPCErrorResponseBody;
+type NSRPCSuccesfulResponseBody = Omit<NSRPCSuccesfulResponse, "nsrpc" | "id">;
+type NSRPCErrorResponseBody = Omit<NSRPCErrorResponse, "nsrpc" | "id">;
+
+interface PromiseSource {
+  resolve: (
+    value: unknown
+  ) => void;
+  reject: (reason?: any) => void;
+}
+type ClosureTarget = (
+  params: Record<string, unknown>
+) => Record<string, unknown> | void;
+
+export class NSRPC {
+  logMessages = false;
+  private readonly send: (data: string) => void;
+
+  private responseHandlers: Map<string, PromiseSource> = new Map();
+  private closureTargets: Map<string, ClosureTarget> = new Map();
+
+  constructor(send: (data: string) => void) {
+    this.send = send;
+  }
+
+  receive(data: string) {
+    // TODO: For now we just assume the message is a valid NSRPC message, but we should:
+    // - Check if the nsrpc property is set to a number in the range of 1..<2
+    // - Validate the message against the defined interfaces above
+    let message: NSRPCMessage
+    try {
+      if (this.logMessages) {
+        console.log("< ", data.trimEnd());
+      }
+      message = JSON.parse(data) as NSRPCMessage;
+    } catch (error) {
+      if (this.logMessages) {
+        console.log("!! Above message is invalid JSON, will be ignored.");
+      }
+      return;
+    }
+
+    if ("status" in message) {
+      // This is a response, dispatch it so it can be handled
+      const responseHandler = this.responseHandlers.get(message.id);
+      this.responseHandlers.delete(message.id);
+      if (responseHandler === undefined) {
+        // TODO: Got a response for a request we don't know about, log this
+        return;
+      }
+
+      if ("error" in message) {
+        responseHandler.reject(message.error);
+      } else {
+        responseHandler.resolve(message.result);
+      }
+    } else {
+      // This is a request
+      const responseBody = this.handleRequest(message);
+      if (responseBody !== undefined) {
+        this.sendResponse(message.id, responseBody);
+      }
+    }
+  }
+
+  /* Sending helpers */
+
+  private sendMessage(message: NSRPCMessage) {
+    const stringMessage = JSON.stringify(message)
+    if (this.logMessages) {
+      console.log("> ", stringMessage);
+    }
+    this.send(stringMessage);
+  }
+
+  private sendResponse(id: string | undefined, response: NSRPCResponseBody) {
+    if (id === undefined) {
+      return;
+    }
+    this.sendMessage({ ...response, nsrpc: 1, id });
+  }
+
+  private async sendRequest(
+    request: NSRPCRequestBody
+  ): Promise<unknown> {
+    const id = "req_" + randomUUID();
+    const response = new Promise((resolve, reject) => {
+      this.responseHandlers.set(id, { resolve, reject });
+    });
+
+    this.sendMessage({ ...request, nsrpc: 1, id });
+
+    return response;
+  }
+
+  /* Request handling */
+
+  private handleRequest(request: NSRPCRequest): NSRPCResponseBody | undefined {
+    switch (request.procedure) {
+      case "init":
+        return {
+          status: 501,
+          error: {
+            debugDescription: "Init procedure not implemented.",
+            userMessage:
+              "Failed to communicate with external process. (Procedure not implemented)",
+          },
+        };
+      case "perform":
+        if ("action" in request) {
+          return {
+            status: 501,
+            error: {
+              debugDescription:
+                "Perform procedure for (static) methods not implemented.",
+              userMessage:
+                "Failed to communicate with external process. (Procedure not implemented)",
+            },
+          };
+        } else {
+          return this.handleClosureRequest(request);
+        }
+      case "release":
+        return {
+          status: 501,
+          error: {
+            debugDescription: "Release procedure not implemented.",
+            userMessage:
+              "Failed to communicate with external process. (Procedure not implemented)",
+          },
+        };
+    }
+  }
+
+  private handleClosureRequest(
+    request: NSRPCPerformClosureRequest
+  ): NSRPCResponseBody {
+    const handler = this.closureTargets.get(request.target);
+    if (handler === undefined) {
+      return {
+        status: 404,
+        error: {
+          debugDescription: `Perform target '${request.target}' not found.`,
+          userMessage:
+            "Failed to communicate with external process. (Target not found)",
+        },
+      };
+    }
+
+    try {
+      const rawresult = handler(request.params ?? {});
+      const result = rawresult === undefined ? undefined : rawresult;
+      return {
+        status: 200,
+        result,
+      };
+    } catch (error) {
+      return {
+        status: 202,
+        // TODO: Would be good to have an error type that we can throw that fills these fields more specifically. (But for now it doesn't matter since this is just communicated back the the CLI and not to the user.)
+        error: {
+          debugDescription: `${error}`,
+          userMessage: "Handler failed to perform request.",
+          underlyingError: error,
+        },
+      };
+    }
+  }
+
+  /* Perform remote procedures */
+
+  async initialize(args: {
+    target: string;
+    type: string;
+    params?: Record<string, unknown>;
+    lifecycle: Object;
+  }) {
+    const target = args.target
+    finalizationRegistry.register(args.lifecycle, async () => {
+      await this.release(target);
+    });
+
+    await this.sendRequest({
+      target: args.target,
+      type: args.type,
+      params: args.params,
+      procedure: "init",
+    });
+  }
+
+  async perform(body: { // TODO: Add support for static method calls.
+    type?: string;
+    target?: string;
+    action?: string;
+    params?: Record<string, unknown>;
+  }): Promise<unknown> {
+    return await this.sendRequest({
+      ...body,
+      procedure: "perform",
+    } as any);
+  }
+
+  private async release(target: string) {
+    await this.sendRequest({
+      procedure: "release",
+      target,
+    });
+  }
+
+  /* Register locally available targets/actions */
+
+  registerClosure(options: {
+    handler: ClosureTarget;
+    lifecycle: Object;
+    prefix: string;
+  }): string {
+    const target = `target_${options.prefix}_${randomUUID()}`;
+    this.closureTargets.set(target, options.handler);
+
+    finalizationRegistry.register(options.lifecycle, () => {
+      this.closureTargets.delete(target);
+    });
+
+    return target;
+  }
+}

package/src/RecordKit.ts

@@ -0,0 +1,99 @@
+import { IpcRecordKit } from "./IpcRecordKit.js";
+import { Recorder, RecorderSchema, AbortReason } from "./Recorder.js";
+import { existsSync } from "node:fs";
+
+type AuthorizationStatus =
+  | 'notDetermined' // The user has not yet made a choice.
+  | 'restricted' // The user cannot change the client's status, possibly due to active restrictions such as parental controls being in place.
+  | 'denied' // The user explicitly denied access to the hardware supporting a media type for the client.
+  | 'authorized' // Application is authorized to access the hardware.
+
+export interface Window {
+  id: number; // UInt32
+  title?: string;
+  frame: Bounds
+  level: number // Int
+  application_process_id?: number // Int32
+  application_name?: string
+}
+
+export interface Camera {
+  id: string;
+  name: string;
+  model_id: string;
+  manufacturer: string;
+  availability: 'available' | 'lidClosed' | 'unknownSuspended'
+}
+
+export interface Microphone {
+  id: string;
+  name: string;
+  model_id: string;
+  manufacturer: string;
+  availability: 'available' | 'lidClosed' | 'unknownSuspended'
+}
+
+export interface Bounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export class RecordKit {
+  private ipcRecordKit = new IpcRecordKit()
+
+  async initialize(args: { rpcBinaryPath: string, fallbackToNodeModules: boolean, logRpcMessages?: boolean }): Promise<void> {
+    let rpcBinaryPath = args.rpcBinaryPath
+    if (args.fallbackToNodeModules) {
+      if (!existsSync(rpcBinaryPath)) {
+        console.log('Falling back to RPC binary from node_modules, no file at given RPC binary path.')
+        rpcBinaryPath = rpcBinaryPath.replace('node_modules/electron/dist/Electron.app/Contents/Resources', 'node_modules/@nonstrict/recordkit/bin')
+      }
+    }
+
+    return this.ipcRecordKit.initialize(rpcBinaryPath, args.logRpcMessages)
+  }
+
+  async getWindows(): Promise<Window[]> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'getWindows' }) as Window[]
+  }
+
+  async getCameras(): Promise<Camera[]> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'getCameras' }) as Camera[]
+  }
+
+  async getMicrophones(): Promise<Microphone[]> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'getMicrophones' }) as Microphone[]
+  }
+
+  async getCameraAuthorizationStatus(): Promise<AuthorizationStatus> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'getCameraAuthorizationStatus' }) as AuthorizationStatus
+  }
+
+  async getMicrophoneAuthorizationStatus(): Promise<AuthorizationStatus> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'getMicrophoneAuthorizationStatus' }) as AuthorizationStatus
+  }
+
+  async getScreenRecordingAccess(): Promise<boolean> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'getScreenRecordingAccess' }) as boolean
+  }
+
+  async requestCameraAccess(): Promise<boolean> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'requestCameraAccess' }) as boolean
+  }
+
+  async requestMicrophoneAccess(): Promise<boolean> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'requestMicrophoneAccess' }) as boolean
+  }
+
+  async requestScreenRecordingAccess(): Promise<void> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'requestScreenRecordingAccess' }) as void
+  }
+
+  async createRecorder(schema: RecorderSchema): Promise<Recorder> {
+    return Recorder.newInstance(this.ipcRecordKit.nsrpc, schema);
+  }
+}
+
+export let recordkit = new RecordKit();