@pymthouse/builder-sdk 0.0.8 → 0.3.0

package/gateway/proto/lp_rpc.proto

@@ -0,0 +1,542 @@
+syntax = "proto3";
+
+package net;
+option go_package = "./net";
+
+// RPC calls implemented by the orchestrator
+service Orchestrator {
+
+  // Called by the broadcaster to request transcoder info from an orchestrator.
+  rpc GetOrchestrator(OrchestratorRequest) returns (OrchestratorInfo);
+  rpc EndTranscodingSession(EndTranscodingSessionRequest)
+      returns (EndTranscodingSessionResponse);
+  rpc Ping(PingPong) returns (PingPong);
+}
+
+service AIWorker {
+
+  // Called by the aiworker to register to an orchestrator. The orchestrator
+  // notifies registered aiworkers of jobs as they come in.
+  rpc RegisterAIWorker(RegisterAIWorkerRequest) returns (stream NotifyAIJob);
+}
+
+service Transcoder {
+
+  // Called by the transcoder to register to an orchestrator. The orchestrator
+  // notifies registered transcoders of segments as they come in.
+  rpc RegisterTranscoder(RegisterRequest) returns (stream NotifySegment);
+}
+
+message PingPong {
+  // Implementation defined
+  bytes value = 1;
+}
+
+// sent by Broadcaster to Orchestrator to terminate the transcoding session and
+// free resources (used for verification sessions)
+message EndTranscodingSessionRequest {
+  // Data for transcoding authentication
+  AuthToken auth_token = 1;
+}
+
+message EndTranscodingSessionResponse {}
+
+// This request is sent by the broadcaster in `GetTranscoder` to request
+// information on which transcoder to use.
+message OrchestratorRequest {
+
+  // Ethereum address of the broadcaster
+  bytes address = 1;
+
+  // Broadcaster's signature over its address
+  bytes sig = 2;
+
+  // Features and constraints required by the broadcaster
+  Capabilities capabilities = 3;
+
+  // Don't throw error in case of missing capacity, used for refreshing session
+  // when we don't need to check capacity
+  bool ignoreCapacityCheck = 4;
+}
+
+/*
+  OSInfo needed to negotiate storages that will be used.
+  It carries info needed to write to the storage.
+*/
+message OSInfo {
+
+  enum StorageType {
+    DIRECT = 0;
+    S3 = 1;
+    GOOGLE = 2;
+  }
+
+  // Storage type: direct, s3, ipfs.
+  StorageType storageType = 1;
+
+  S3OSInfo s3info = 16;
+}
+
+message S3OSInfo {
+
+  // Host to use to connect to S3
+  string host = 1;
+
+  // Key (prefix) to use when uploading the object.
+  string key = 2;
+
+  // POST policy that S3 owner node creates to give write access to other node.
+  string policy = 3;
+
+  // Signature for POST policy.
+  string signature = 4;
+
+  // Needed for POST policy.
+  string credential = 5;
+
+  // Needed for POST policy.
+  string xAmzDate = 6;
+}
+
+// PriceInfo conveys pricing info for transcoding services
+message PriceInfo {
+  // price in wei
+  int64 pricePerUnit = 1;
+
+  // Pixels covered in the price
+  // Set price to 1 wei and pixelsPerUnit > 1 to have a smaller price
+  // granularity per pixel than 1 wei
+  int64 pixelsPerUnit = 2;
+
+  // Capability price is for
+  uint32 capability = 3;
+
+  // constraint price is for
+  string constraint = 4;
+}
+
+message Capabilities {
+
+  // Bit string of supported features - one bit per feature
+  repeated uint64 bitstring = 1;
+
+  // Bit string of features that are required to be supported
+  repeated uint64 mandatories = 2;
+
+  // Capacity corresponding to each capability
+  map<uint32, uint32> capacities = 3;
+
+  string version = 4;
+
+  Constraints constraints = 5;
+
+  // Non-binary constraints.
+  message Constraints {
+    string minVersion = 1;
+    map<uint32, CapabilityConstraints> PerCapability = 2;
+  }
+
+  // Non-binary capability constraints, such as supported ranges.
+  message CapabilityConstraints {
+    message ModelConstraint {
+      bool warm = 1;
+      uint32 capacity = 2;
+      string runnerVersion = 3;
+      uint32 capacityInUse = 4;
+    }
+
+    map<string, ModelConstraint> models = 1;
+  }
+}
+
+// The orchestrator sends this in response to `GetOrchestrator`, containing
+// miscellaneous data related to the job.
+message OrchestratorInfo {
+
+  // URI of the transcoder to use for submitting segments.
+  string transcoder = 1;
+
+  // Parameters for probabilistic micropayment tickets
+  TicketParams ticket_params = 2;
+
+  // Price Info containing the price per pixel to transcode
+  PriceInfo price_info = 3;
+
+  // ETH address that should sign transcoded results
+  bytes address = 4;
+
+  // Features and constraints supported by the orchestrator
+  Capabilities capabilities = 5;
+
+  // Data for transcoding authentication
+  AuthToken auth_token = 6;
+
+  // Information on Orchestrator hardware
+  repeated HardwareInformation hardware = 7;
+
+  // Orchestrator returns info about own input object storage, if it wants it to
+  // be used.
+  repeated OSInfo storage = 32;
+
+  // prices for capabilities
+  repeated PriceInfo capabilities_prices = 33;
+
+  // List of other node URIs belonging to this orchestrator.
+  repeated string nodes = 34;
+}
+
+// Data for transcoding authentication that is included in the OrchestratorInfo
+// message during discovery
+message AuthToken {
+  // Record used to authenticate for a transcode session
+  // Opaque to the receiver
+  bytes token = 1;
+
+  // ID of the transcode session that the token is authenticating for
+  string session_id = 2;
+
+  // Timestamp when the token expires
+  int64 expiration = 3;
+}
+
+// Data included by the broadcaster when submitting a segment for transcoding.
+message SegData {
+
+  // Manifest ID this segment belongs to
+  bytes manifestId = 1;
+
+  // Sequence number of the segment to be transcoded
+  int64 seq = 2;
+
+  // Hash of the segment data to be transcoded
+  bytes hash = 3;
+
+  // Transcoding profiles to use
+  bytes profiles = 4;
+
+  // Broadcaster signature for the segment. Corresponds to:
+  // broadcaster.sign(manifestId | seqNo | dataHash | profiles)
+  bytes sig = 5;
+
+  // Duration of the segment to be transcoded, in milliseconds
+  int32 duration = 6;
+
+  // Capabilities used by this segment.
+  Capabilities capabilities = 7;
+
+  // Data for transcoding authentication
+  AuthToken auth_token = 8;
+
+  // Calculate perceptual hash for this segment
+  bool calc_perceptual_hash = 10;
+
+  // Broadcaster's preferred storage medium(s)
+  // XXX should we include this in a sig somewhere until certs are
+  // authenticated?
+  repeated OSInfo storage = 32;
+
+  // Transcoding profiles to use. Supersedes `profiles` field
+  // Deprecated by `fullProfiles2` but may still be used for mpegts formats
+  repeated VideoProfile fullProfiles = 33;
+
+  // Transcoding profiles to use. Supersedes `fullProfiles` field
+  // Deprecated by `fullProfiles3` but may still be used for integer FPS
+  repeated VideoProfile fullProfiles2 = 34;
+
+  // Transcoding profiles to use. Supersedes `fullProfiles2` field
+  repeated VideoProfile fullProfiles3 = 35;
+
+  // Transcoding parameters specific to this segment
+  SegParameters segment_parameters = 37;
+
+  // Force HW Session Reinit
+  bool ForceSessionReinit = 38;
+}
+
+message SegParameters {
+  // Start timestamp from which to start encoding
+  // Milliseconds, from start of the file
+  uint64 from = 1;
+  // Skip all frames after that timestamp
+  // Milliseconds, from start of the file
+  uint64 to = 2;
+}
+
+message VideoProfile {
+  // Name of VideoProfile
+  string name = 16;
+
+  // Width of VideoProfile
+  int32 width = 17;
+
+  // Height of VideoProfile
+  int32 height = 18;
+
+  // Bitrate of VideoProfile
+  int32 bitrate = 19;
+
+  // FPS of VideoProfile
+  uint32 fps = 20;
+
+  // Desired output format
+  enum Format {
+    MPEGTS = 0;
+    MP4 = 1;
+  }
+  Format format = 21;
+
+  // FPS Denominator of VideoProfile
+  uint32 fpsDen = 22;
+
+  enum Profile {
+    ENCODER_DEFAULT = 0;
+    H264_BASELINE = 1;
+    H264_MAIN = 2;
+    H264_HIGH = 3;
+    H264_CONSTRAINED_HIGH = 4;
+  }
+  // Desired codec profile
+  Profile profile = 23;
+
+  // GOP interval
+  int32 gop = 24;
+
+  enum VideoCodec {
+    H264 = 0;
+    H265 = 1;
+    VP8 = 2;
+    VP9 = 3;
+  }
+
+  // Encoder (video codec)
+  VideoCodec encoder = 25;
+
+  int32 colorDepth = 26;
+
+  enum ChromaSubsampling {
+    CHROMA_420 = 0;
+    CHROMA_422 = 1;
+    CHROMA_444 = 2;
+  }
+  ChromaSubsampling chromaFormat = 27;
+  uint32 quality = 28;
+}
+
+// Individual transcoded segment data.
+message TranscodedSegmentData {
+
+  // URL where the transcoded data can be downloaded from.
+  string url = 1;
+
+  // Amount of pixels processed (output pixels)
+  int64 pixels = 2;
+
+  // URL where the perceptual hash data can be downloaded from (can be empty)
+  string perceptual_hash_url = 3;
+}
+
+// A set of transcoded segments following the profiles specified in the job.
+message TranscodeData {
+
+  // Transcoded data, in the order specified in the job options
+  repeated TranscodedSegmentData segments = 1;
+
+  // Signature of the hash of the concatenated hashes
+  bytes sig = 2;
+}
+
+// Response that a transcoder sends after transcoding a segment.
+message TranscodeResult {
+
+  // Sequence number of the transcoded results.
+  int64 seq = 1;
+
+  // Result of transcoding can be an error, or successful with more info
+  oneof result {
+    string error = 2;
+    TranscodeData data = 3;
+  }
+
+  // Used to notify a broadcaster of updated orchestrator information
+  OrchestratorInfo info = 16;
+}
+
+// Response that an orchestrator sends after processing a payment.
+message PaymentResult {
+  // Used to notify a broadcaster of updated orchestrator information
+  OrchestratorInfo info = 16;
+}
+
+// Sent by the transcoder to register itself to the orchestrator.
+message RegisterRequest {
+
+  // Shared secret for auth
+  string secret = 1;
+
+  // Transcoder capacity
+  int64 capacity = 2;
+
+  // Transcoder capabilities
+  Capabilities capabilities = 3;
+}
+
+// Sent by the orchestrator to the transcoder
+message NotifySegment {
+
+  // URL of the segment to transcode.
+  string url = 1;
+
+  // Configuration for the transcoding job
+  SegData segData = 3;
+
+  // ID for this particular transcoding task.
+  int64 taskId = 16;
+
+  // Orchestrator identifier for segment metadata
+  string orchId = 18;
+
+  // All fields below are deprecated. May still be populated if necessary
+
+  // Deprecated by segData. Job the segment belongs to.
+  reserved 2; // Formerly "string job"
+
+  // Deprecated by fullProfiles. Set of presets to transcode into.
+  // Should be set to an invalid value to induce failures
+  bytes profiles = 17;
+
+  // Deprecated by segData. Transcoding configuration to use.
+  reserved 33; // Formerly "repeated VideoProfile fullProfiles"
+}
+
+// Sent by the aiworker to register itself to the orchestrator.
+message RegisterAIWorkerRequest {
+
+  // Shared secret for auth
+  string secret = 1;
+
+  // AIWorker capabilities
+  Capabilities capabilities = 2;
+
+  // AIWorker hardware info
+  repeated HardwareInformation hardware = 3;
+}
+
+// Data included by the gateway when submitting a AI job.
+message AIJobData {
+  // pipeline to use for the job
+  string pipeline = 1;
+
+  // AI job request data
+  bytes requestData = 2;
+}
+
+// Sent by the orchestrator to the aiworker
+message NotifyAIJob {
+  // Configuration for the AI job
+  AIJobData AIJobData = 1;
+
+  // ID for this particular AI task.
+  int64 taskId = 2;
+}
+
+// Required parameters for probabilistic micropayment tickets
+message TicketParams {
+  // ETH address of the recipient
+  bytes recipient = 1;
+
+  // Pay out (in Wei) to the recipient if the ticket wins
+  bytes face_value = 2;
+
+  // Probability that the ticket wins
+  bytes win_prob = 3;
+
+  // 32 byte keccak-256 hash commitment to a random number provided
+  // by the recipient
+  bytes recipient_rand_hash = 4;
+
+  // Value generated by recipient that the recipient can use
+  // to derive the random number corresponding to the recipient's hash
+  // commitment
+  bytes seed = 5;
+
+  // Block number at which the current set of advertised TicketParams is no
+  // longer valid
+  bytes expiration_block = 6;
+
+  // Expected ticket expiration params
+  TicketExpirationParams expiration_params = 7;
+}
+
+// Sender Params (nonces and signatures)
+message TicketSenderParams {
+  // Monotonically increasing counter that makes the ticket
+  // unique relative to a particular hash commitment to a recipient's random
+  // number
+  uint32 sender_nonce = 1;
+
+  // Sender signature over the ticket
+  bytes sig = 2;
+}
+
+// Ticket params for expiration related validation
+message TicketExpirationParams {
+  // Round during which tickets are created
+  int64 creation_round = 1;
+
+  // Block hash associated with creation_round
+  bytes creation_round_block_hash = 2;
+}
+
+// Payment for transcoding video segments
+// A payment can constitute of multiple tickets
+// A broadcaster might need to send multiple tickets to top up his credit with
+// an Orchestrator
+message Payment {
+  // Probabilistic micropayment ticket parameters
+  // These remain the same even when sending multiple tickets
+  TicketParams ticket_params = 1;
+
+  // ETH address of the sender
+  bytes sender = 2;
+
+  // Ticket params for expiration related validation
+  TicketExpirationParams expiration_params = 3;
+
+  repeated TicketSenderParams ticket_sender_params = 4;
+
+  // O's last known price
+  PriceInfo expected_price = 5;
+}
+
+// GPU information used by worker on network
+message GPUComputeInfo {
+  // unique id
+  string id = 1;
+
+  // gpu name
+  string name = 2;
+
+  // compute version supported - major
+  uint32 major = 4;
+
+  // compute version supported - minor
+  uint32 minor = 5;
+
+  // GPU memory free
+  int64 memory_free = 6;
+
+  // GPU memory total
+  int64 memory_total = 7;
+}
+
+// Hardware information for worker on network
+message HardwareInformation {
+  // pipeline hardware supports
+  string pipeline = 1;
+
+  // model_id hardware supports
+  string model_id = 2;
+
+  // hardware for pipeline and model_id
+  map<string, GPUComputeInfo> gpu_info = 3;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pymthouse/builder-sdk",
-  "version": "0.0.8",
+  "version": "0.3.0",
   "description": "PymtHouse Builder API and OIDC client (OpenID-certified oauth4webapi)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -12,6 +12,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./plan-pricing": {
+      "types": "./dist/plan-pricing.d.ts",
+      "import": "./dist/plan-pricing.js",
+      "require": "./dist/plan-pricing.cjs"
+    },
     "./format": {
       "types": "./dist/format.d.ts",
       "import": "./dist/format.js",
@@ -22,22 +27,70 @@
       "import": "./dist/env.js",
       "require": "./dist/env.cjs"
     },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "require": "./dist/config.cjs"
+    },
+    "./tokens": {
+      "types": "./dist/tokens.d.ts",
+      "import": "./dist/tokens.js",
+      "require": "./dist/tokens.cjs"
+    },
     "./device": {
       "types": "./dist/device.d.ts",
       "import": "./dist/device.js",
       "require": "./dist/device.cjs"
     },
+    "./device-initiate": {
+      "types": "./dist/device-initiate.d.ts",
+      "import": "./dist/device-initiate.js",
+      "require": "./dist/device-initiate.cjs"
+    },
     "./verify": {
       "types": "./dist/verify.d.ts",
       "import": "./dist/verify.js",
       "require": "./dist/verify.cjs"
+    },
+    "./signer/server": {
+      "types": "./dist/signer/server.d.ts",
+      "import": "./dist/signer/server.js",
+      "require": "./dist/signer/server.cjs"
+    },
+    "./gateway": {
+      "types": "./dist/gateway/index.d.ts",
+      "import": "./dist/gateway/index.js",
+      "require": "./dist/gateway/index.cjs"
+    },
+    "./gateway/client": {
+      "types": "./dist/gateway/client/index.d.ts",
+      "import": "./dist/gateway/client/index.js",
+      "require": "./dist/gateway/client/index.cjs"
+    },
+    "./gateway/server": {
+      "types": "./dist/gateway/server/index.d.ts",
+      "import": "./dist/gateway/server/index.js",
+      "require": "./dist/gateway/server/index.cjs"
     }
   },
   "files": [
     "dist",
+    "gateway/proto",
     "README.md",
     "LICENSE"
   ],
+  "peerDependencies": {
+    "@grpc/grpc-js": "^1.12.0",
+    "@grpc/proto-loader": "^0.7.0"
+  },
+  "peerDependenciesMeta": {
+    "@grpc/grpc-js": {
+      "optional": true
+    },
+    "@grpc/proto-loader": {
+      "optional": true
+    }
+  },
   "sideEffects": false,
   "engines": {
     "node": ">=20"
@@ -50,6 +103,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "test": "vitest run",
+    "check:gateway-peers": "node scripts/check-gateway-peers.mjs",
     "format": "prettier . --write",
     "format:check": "prettier . --check",
     "prepack": "pnpm run build"
@@ -58,6 +112,8 @@
     "oauth4webapi": "^3.8.5"
   },
   "devDependencies": {
+    "@grpc/grpc-js": "^1.14.3",
+    "@grpc/proto-loader": "^0.8.0",
     "@eslint/js": "^9.18.0",
     "@types/node": "^22.10.0",
     "eslint": "^9.18.0",

package/dist/env-4YmzarGJ.d.ts

@@ -1,68 +0,0 @@
-import { f as PmtHouseClientOptions, G as GetDiscoveryOptions, O as OidcDiscoveryDocument, P as ParsedDeviceApprovalRedirect, A as AppUserRecord, g as UpsertAppUserInput, M as MintUserAccessTokenInput, d as MintUserAccessTokenResponse, D as DeviceApprovalInput, T as TokenExchangeResponse, C as ClientCredentialsTokenResponse, e as MintUserSignerSessionTokenInput, h as UsageQueryInput, b as UsageApiResponse } from './types-W9PJAspR.js';
-
-/**
- * Normalize RFC 8628 user codes for comparison and resource URIs (uppercase, strip separators).
- */
-declare function normalizeUserCode(value: string): string;
-/**
- * RFC 8707 resource indicator for NaaP Option B device approval (`urn:pmth:device_code:<normalized>`).
- */
-declare function buildDeviceCodeResource(userCode: string): string;
-declare class PmtHouseClient {
-    private readonly issuerUrl;
-    private readonly publicClientId;
-    private readonly m2mClientId;
-    private readonly m2mClientSecret;
-    private readonly fetchImpl;
-    private readonly logger?;
-    private readonly allowInsecureHttp;
-    constructor(options: PmtHouseClientOptions);
-    getDiscovery(options?: GetDiscoveryOptions): Promise<OidcDiscoveryDocument>;
-    verifyIssuer(iss: string): boolean;
-    parseDeviceApprovalRedirect(searchParams: URLSearchParams): ParsedDeviceApprovalRedirect;
-    listAppUsers(): Promise<{
-        users: AppUserRecord[];
-    }>;
-    upsertAppUser(input: UpsertAppUserInput): Promise<AppUserRecord>;
-    deleteAppUser(params: {
-        externalUserId: string;
-    }): Promise<{
-        success: boolean;
-    }>;
-    mintUserAccessToken(input: MintUserAccessTokenInput): Promise<MintUserAccessTokenResponse>;
-    completeDeviceApproval(input: DeviceApprovalInput): Promise<TokenExchangeResponse>;
-    issueMachineAccessToken(scope?: string): Promise<ClientCredentialsTokenResponse>;
-    exchangeForSignerSession(input: {
-        userJwt: string;
-        resource?: string;
-    }): Promise<TokenExchangeResponse>;
-    /**
-     * Mint a short-lived per-user JWT with the Builder API, then exchange it for
-     * a long-lived opaque signer session token at the PymtHouse OIDC token endpoint.
-     */
-    mintUserSignerSessionToken(input: MintUserSignerSessionTokenInput): Promise<TokenExchangeResponse>;
-    createSignerSessionToken(params: {
-        userJwt?: string;
-    }): Promise<TokenExchangeResponse>;
-    getUsage(input?: UsageQueryInput): Promise<UsageApiResponse>;
-    private tokenEndpointFetchOptions;
-    private getAppsBaseUrl;
-    private getIssuerOrigin;
-    private builderHeaders;
-    private m2mClientAuth;
-    private requestJson;
-    private safeParseJson;
-    private asError;
-}
-
-/**
- * Site origin for the PymtHouse deployment (e.g. https://pymthouse.com), derived
- * from `PYMTHOUSE_ISSUER_URL`.
- */
-declare function getPymthouseBaseUrl(): string;
-/**
- * Singleton `PmtHouseClient` from `PYMTHOUSE_*` environment variables (server-side).
- */
-declare function createPmtHouseClientFromEnv(): PmtHouseClient;
-
-export { PmtHouseClient as P, buildDeviceCodeResource as b, createPmtHouseClientFromEnv as c, getPymthouseBaseUrl as g, normalizeUserCode as n };