@supersuit/suggest-a-change 0.1.12 → 0.2.0

package/dist/github/relay.d.ts

@@ -0,0 +1,159 @@
+import { type GeoHook } from '../server/geo.ts';
+import { type Fetch } from './api.ts';
+import { type Person } from './privacy.ts';
+/** A voice recording's ceiling; the same number as the server half's VOICE_FILE_BYTES (a test holds them together). */
+export declare const RELAY_VOICE_BYTES: number;
+export interface RelayLimits {
+    /** Different reports one identity may file or attach to in a day. */
+    perPersonPerDay: number;
+    /** Bytes of files one identity may send in a day, across every action. */
+    bytesPerPersonPerDay: number;
+    images: number;
+    imageBytes: number;
+    videos: number;
+    videoBytes: number;
+    /** Recordings per report: the report's voice notes and those added to it later. */
+    voice: number;
+    voiceBytes: number;
+    /** How long after an issue closed a file may still be attached to it. */
+    closedGraceMs: number;
+    /** The largest file taken inside a request body. A larger one is staged (upload-url), or refused without staging.
+     *  Serverless hosts cap a request body (Vercel at about 4.5 MB), so the default leaves room for base64 and the rest. */
+    inlineBytes: number;
+}
+export declare const RELAY_LIMITS: RelayLimits;
+export interface FiledRecord {
+    account: string;
+    reportId: string;
+    number: number;
+    url: string;
+}
+/** A day's allowance held for one request, until it is committed (it happened) or released (it did not). */
+export type Reservation = {
+    ok: true;
+    token: string;
+} | {
+    ok: false;
+    over: 'reports' | 'bytes';
+};
+/** What the relay remembers. Every method is ATOMIC in a real store (one transaction or a conditional write): a check
+ *  and the change it guards are one step, so two requests at once can never both pass a cap of one. */
+export interface RelayUsage {
+    /** Holds today's allowance for this request: one more report (unless `reportId` was already counted today for
+     *  `account`) and `bytes` more bytes, refusing when either would pass its limit. Nothing is held on a refusal. */
+    reserve(account: string, day: string, reportId: string, bytes: number, limits: {
+        reports: number;
+        bytes: number;
+    }): Promise<Reservation>;
+    /** The request that reserved this happened: keep it. */
+    commit(token: string): Promise<void>;
+    /** The request that reserved this did not happen: give it back. */
+    release(token: string): Promise<void>;
+    /** A report belongs to the first identity that files or attaches for it: 'ok' for that identity, 'taken' for anyone else. */
+    bind(repo: string, reportId: string, account: string): Promise<'ok' | 'taken'>;
+    /** Starts filing a report, first caller wins: 'go', or 'busy' while another filing of it runs, or the record of the issue it already became. */
+    /** Starts filing a report under a lease of `leaseMs`, first caller wins: 'go', or 'busy' while another filing of it holds a
+     *  live lease, or the record of the issue it already became. A lease past its time is taken over (its process died). */
+    begin(repo: string, reportId: string, account: string, leaseMs: number): Promise<{
+        state: 'go';
+    } | {
+        state: 'busy';
+    } | ({
+        state: 'filed';
+    } & FiledRecord)>;
+    /** upload-url issued a link for this staging key, for at most `bytes`: a later read is bounded by it. */
+    stage(key: string, bytes: number): Promise<void>;
+    /** The bytes upload-url held for this key, or null when it never issued one. */
+    staged(key: string): Promise<number | null>;
+    /** The staged file was written and discarded: forget its key. */
+    unstage(key: string): Promise<void>;
+    /** The filing that began succeeded: keep the record, by report and by issue number. */
+    finish(repo: string, record: FiledRecord): Promise<void>;
+    /** The filing that began failed: forget it, so a retry can begin again. */
+    abandon(repo: string, reportId: string): Promise<void>;
+    /** Who filed this issue through the relay, or null. */
+    filer(repo: string, number: number): Promise<FiledRecord | null>;
+}
+/** In memory, so ONE SERVER INSTANCE ONLY: a platform that runs several instances (most serverless hosts) needs a store
+ *  backed by its database, or the caps, the idempotency and who-filed-what are per instance and lost on restart. Each
+ *  method below changes what it checks before it yields, which is what makes it atomic in one process. */
+export declare function memoryUsage({ now }?: {
+    now?: () => number;
+}): RelayUsage;
+/** Who is calling, as the host knows them. The issue's name, role, app and contact come from here and never from the
+ *  request: a request can say whether to share the contact (it sends `report.who.contact`), never what it is. */
+export interface RelayIdentity {
+    account: string;
+    /** The name the issue says it was filed by; "Someone" without one. */
+    name?: string;
+    role?: 'operator' | 'member' | 'maintainer';
+    /** The GitHub login this person files under, when the host knows it: `attach` to an issue the relay did not file
+     *  is accepted only when that issue was opened by this login. */
+    githubLogin?: string;
+    /** How to reach them, shared only when the request asks (the person left it ticked). */
+    contact?: {
+        email?: string;
+        phone?: string;
+        handle?: string;
+    };
+}
+export interface SuggestionRelayOptions {
+    /** The GitHub App the relay acts as: its numeric id and its private key (PEM, PKCS#1 as GitHub issues it, or PKCS#8). */
+    app: {
+        id: number | string;
+        privateKey: string;
+    };
+    /** Who is calling, from the request (a session, an API key, whatever the server already uses), or null. */
+    identity(req: Request): Promise<RelayIdentity | null>;
+    /** The repos this identity may file on; null (or no function) means any repo the App is installed on. */
+    repos?(account: string): string[] | null | Promise<string[] | null>;
+    /** What the privacy catch looks for besides credentials, emails and phones: third parties, and secrets the host knows. */
+    privacy?: {
+        people?: Person[];
+        secrets?: string[];
+    };
+    /** Roughly where the filer was, from the request (see the server half's geo hooks); added to the issue's context. */
+    geo?: GeoHook;
+    /** The apps this relay files for, by the id a request names (`app`): the issue's app name and its `app:<label>`
+     *  come from here. A request naming an app not in the table is refused; without a table no request names one. */
+    apps?: Record<string, {
+        name: string;
+        label: string;
+    }>;
+    /** Where files too large for one request body wait: the filer PUTs each to a one-time signed link (`upload-url`),
+     *  and `file` or `attach` names it as `staged`. Without it, only files up to `inlineBytes` can be sent. */
+    staging?: StagingAdapter;
+    /** May lower any limit, never raise one. */
+    limits?: Partial<RelayLimits>;
+    usage?: RelayUsage;
+    fetch?: Fetch;
+    now?: () => number;
+    /** Default https://api.github.com */
+    api?: string;
+}
+/** The 0.2.0 name, for a relay that only attaches. */
+export type AttachRelayOptions = SuggestionRelayOptions;
+/** A bucket the relay controls, for files past a request body limit. `uploadUrl` answers a one-time signed PUT that
+ *  can only create `key` once, with this type and at most these bytes: on Google Cloud Storage a V4 signed URL for PUT
+ *  with `x-goog-if-generation-match: 0` and `x-goog-content-length-range: 0,<bytes>` as signed headers; on S3 a
+ *  presigned PUT with `If-None-Match: *` and the content type and length signed. `read` answers what arrived (or null),
+ *  `discard` deletes it once the relay has written it to GitHub. */
+export interface StagingAdapter {
+    uploadUrl(key: string, o: {
+        type: string;
+        bytes: number;
+    }): Promise<{
+        url: string;
+        headers?: Record<string, string>;
+    }>;
+    read(key: string): Promise<ReadableStream<Uint8Array> | Uint8Array | ArrayBuffer | null>;
+    discard(key: string): Promise<void>;
+}
+/** How long a filing holds its report before another try may take it over (its process is presumed dead). */
+export declare const FILING_LEASE_MS: number;
+declare const ACTIONS: readonly ['file', 'follow-up', 'status', 'attach', 'upload-url'];
+type Action = (typeof ACTIONS)[number];
+export declare function createSuggestionRelay(opts: SuggestionRelayOptions, only?: Action): (req: Request) => Promise<Response>;
+/** A relay that only attaches (the 0.2.0 shape): every request is `attach`, whatever its path. */
+export declare const createAttachRelay: (opts: AttachRelayOptions) => (req: Request) => Promise<Response>;
+export {};