Skip to content
Oyster0.6.0
API reference

git

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/oyster/git";

Exports

Section titled “Exports”
Kind Export Description
type alias GitStore Installation-scoped storage; transport and credentials stay with its provider adapter.
type alias GitGrants Live host authority, reopened before every provider call. Null is an anonymous reader.
type alias GitPolicy Repository rules owned by the selected App; a missing or malformed answer refuses.
type alias GitJournal Durable accepted-ref journal; record commits before the provider result is acknowledged.
type alias AdmittedGit Host-held read/write path; Apps receive only its installation-authored binding.
type alias GitDoorTarget The repository and access one smart-HTTP request names.
type alias GitDoorHost Identity and selected installation come only from host-held ports.
type alias GitPushJournalPorts The standalone composition supplies selected-Instance admission and its alarm.
type alias EventSink The EVENTS binding: an App emits typed events the host routes.
type alias StandardWebhookPayload The Standard Webhooks payload shape.
function createInstallationGitAdmission() Reuse the live installation/verified Release rule without opening provider storage.
function createAdmittedGit() Fixed order: host grant, Workflow ceiling, App policy, provider exchange, durable journal.
function smartHttpExchange() One smart-HTTP exchange: the method, service query and path suffix a Git client sends, whatever path names the repository. Null otherwise.
function gitDoorRoute() Oyster’s own Git address: the repository, scope and phase one request names, or null when it is not an exact Oyster Git exchange.
function createGitDoor() Mount one smart-HTTP door with no provider credentials or alternate write branch.
function createGitPushJournal() Carrier owns delivery state; this journal owns accepted fact identity.
function lsRefsRequest() The protocol-v2 ls-refs request body.
function parseLsRefs() Parse an ls-refs response into refs.
function signStandardWebhook() The Standard Webhooks webhook-signature value for one delivery.
function webhookHeaders() Headers for one signed delivery: Standard Webhooks plus X-Hub-Signature-256.

GitStoretype alias

Section titled “GitStore”
Signature
type GitStore = GitBinding;

Installation-scoped storage; transport and credentials stay with its provider adapter.

GitGrantstype alias

Section titled “GitGrants”
Signature
type GitGrants = Readonly<{
  admits: Promise<boolean>;
}>;

Live host authority, reopened before every provider call. Null is an anonymous reader.

GitPolicytype alias

Section titled “GitPolicy”
Signature
type GitPolicy = Readonly<{
  authorize: Promise<
    | {
        allowed: z.ZodLiteral<true>;
      }
    | {
        allowed: z.ZodLiteral<false>;
        refused: z.ZodArray<
          z.ZodObject<
            {
              ref: z.ZodString;
              message: z.ZodString;
            },
            z.core.$strict
          >
        >;
      }
  >;
}>;

Repository rules owned by the selected App; a missing or malformed answer refuses.

GitJournaltype alias

Section titled “GitJournal”
Signature
type GitJournal = Readonly<{
  tip: Promise<string | null>;
  record: Promise<void>;
}>;

Durable accepted-ref journal; record commits before the provider result is acknowledged.

AdmittedGittype alias

Section titled “AdmittedGit”
Signature
type AdmittedGit = Readonly<{
  push: Promise<
    Readonly<{
      status: number;
      headers: Readonly<Record<string, string>>;
      body: Uint8Array;
    }>
  >;
  read: Promise<
    Readonly<{
      status: number;
      headers: Readonly<Record<string, string>>;
      body: Uint8Array;
    }>
  >;
  binding: GitBinding;
}>;

Host-held read/write path; Apps receive only its installation-authored binding.

GitDoorTargettype alias

Section titled “GitDoorTarget”
Signature
type GitDoorTarget = Readonly<{
  installationId: string;
  repository: string;
  scope: "read" | "write";
}>;

The repository and access one smart-HTTP request names.

GitDoorHosttype alias

Section titled “GitDoorHost”
Signature
type GitDoorHost = Readonly<{
  authenticate: Promise<
     | Readonly<{
     kind: "actor";
     actor: HostActor;
     role?: "owner" | "member";
     workflow?: WorkflowAttestation & object;
   }>
    | null>;
  isPublic: Promise<boolean>;
  git: Promise<
     | Readonly<{
     push: Promise<Readonly<{
        status: number;
        headers: Readonly<Record<..., ...>>;
        body: Uint8Array;
     }>>;
     read: Promise<Readonly<{
        status: number;
        headers: Readonly<Record<..., ...>>;
        body: Uint8Array;
     }>>;
     binding: GitBinding;
   }>
    | null>;
}>;

Identity and selected installation come only from host-held ports.

GitPushJournalPortstype alias

Section titled “GitPushJournalPorts”
Signature
type GitPushJournalPorts = Readonly<{
  owner: WatchdogSqliteOwner;
  deliver: Promise<void>;
  deliverSync: Promise<PostDeliveryResult>;
  scheduleWake: Promise<void>;
  now?: () => number;
}>;

The standalone composition supplies selected-Instance admission and its alarm.

EventSinktype alias

Section titled “EventSink”
Signature
type EventSink = Readonly<{
  emit: Promise<void>;
}>;

The EVENTS binding: an App emits typed events the host routes.

StandardWebhookPayloadtype alias

Section titled “StandardWebhookPayload”
Signature
type StandardWebhookPayload = Readonly<{
  type: string;
  timestamp: string;
  data: Schema.Json;
}>;

The Standard Webhooks payload shape.

createInstallationGitAdmission()function

Section titled “createInstallationGitAdmission()”
Signature
function createInstallationGitAdmission(
  ports,
): (writer, repository, scope) => Promise<boolean>;

Reuse the live installation/verified Release rule without opening provider storage.

Parameters

Section titled “Parameters”
Parameter Type
ports Readonly<{ currentInstallation: Promise< | Readonly<{ installationId: string; instanceId: InstanceId | null; appId: AppId; release: { releaseId: Schema.refine<ReleaseId, Schema.String>; appId: Schema.refine<AppId, Schema.String>; artifact: Schema.Struct<{ artifactRef: Schema.refine<ArtifactRef, Schema.String>; artifactDigest: Schema.refine<Sha256Digest, Schema.String>; provenance: Schema.Struct<{ sourceRevision: …; sourceTreeDigest: …; buildRecipeDigest: …; }>; }>; }; releasePin: "pinned" | "floating"; authority: { authorityVersion: number; declaredOperationsDigest: Sha256Digest; approvedGrants: readonly Readonly<{ capability: | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | … | …; capabilityApproved: true; operations: readonly …[]; resources: … | …; }>[]; approval: | Readonly<{ by: … | … | …; at: number; authorityVersion: number; }> | null; }; status: "enabled" | "disabled" | "deleted"; visibility: "private" | "public"; approvedAnonymousMethods: readonly Readonly<{ name: string; digest: Sha256Digest; }>[]; anonymousApproval: | Readonly<{ by: | { kind: …; memberId: …; } | { kind: …; agentId: …; } | { kind: …; keyId: …; }; at: number; authorityVersion: number; }> | null; }> | null>; declaration: Promise< | Readonly<{ api?: AppApi; displayName?: string; capabilities: readonly AppCapabilityId[]; calls?: readonly Readonly<{ appId: …; methods: …; }>[]; guidance?: string; handlers: readonly AppHandler[]; receives?: readonly "git.push"[]; icon?: string; roles: readonly AppRole[]; storage?: readonly AppStorageKey[]; commands?: readonly AppDeclaredCommand[]; gills?: readonly AppDeclaredGill[]; backend?: Readonly<{ bindings: readonly …[]; sync?: Readonly<{ method: …; }>; }>; }> | null>; }>

Returns

Section titled “Returns”
Signature
(
   writer,
   repository,
   scope
): Promise<boolean>;

Reopen the host authority for this repository and requested scope.

Parameters

Section titled “Parameters”
Parameter Type
writer GitWriter | null
repository string
scope "read" | "write"

Returns

Section titled “Returns”

Promise<boolean>

createAdmittedGit()function

Section titled “createAdmittedGit()”
Signature
function createAdmittedGit(ports): AdmittedGit;

Fixed order: host grant, Workflow ceiling, App policy, provider exchange, durable journal.

Parameters

Section titled “Parameters”
Parameter Type
ports Readonly<{ installationId: string; store: GitStore; grants: GitGrants; policy: GitPolicy; journal: GitJournal; beforeProvider?: () => void; }>

Returns

Section titled “Returns”

AdmittedGit

smartHttpExchange()function

Section titled “smartHttpExchange()”
Signature
function smartHttpExchange(
  method,
  url,
  suffix,
): Readonly<{
  scope: "read" | "write";
  advertise: boolean;
}> | null;

One smart-HTTP exchange: the method, service query and path suffix a Git client sends, whatever path names the repository. Null otherwise.

Parameters

Section titled “Parameters”
Parameter Type
method string
url URL
suffix string

Returns

Section titled “Returns”

| Readonly<{ scope: "read" | "write"; advertise: boolean; }> | null

gitDoorRoute()function

Section titled “gitDoorRoute()”
Signature
function gitDoorRoute(
  method,
  url,
):
  | (Readonly<{
      installationId: string;
      repository: string;
      scope: "read" | "write";
    }> &
      Readonly<{
        advertise: boolean;
      }>)
  | null;

Oyster’s own Git address: the repository, scope and phase one request names, or null when it is not an exact Oyster Git exchange.

Parameters

Section titled “Parameters”
Parameter Type
method string
url URL

Returns

Section titled “Returns”

| Readonly<{ installationId: string; repository: string; scope: "read" | "write"; }> & Readonly<{ advertise: boolean; }> | null

createGitDoor()function

Section titled “createGitDoor()”
Signature
function createGitDoor(host): Hono;

Mount one smart-HTTP door with no provider credentials or alternate write branch.

Parameters

Section titled “Parameters”
Parameter Type
host GitDoorHost

Returns

Section titled “Returns”

Hono

createGitPushJournal()function

Section titled “createGitPushJournal()”
Signature
function createGitPushJournal(ports): Promise<{
  armSync: Promise<number>;
  tip: string | null;
  accept: Promise<"duplicate" | "recorded">;
  alarm: Promise<void>;
  nextWake: () => number | null;
}>;

Carrier owns delivery state; this journal owns accepted fact identity.

Parameters

Section titled “Parameters”
Parameter Type
ports GitPushJournalPorts

Returns

Section titled “Returns”

Promise<{ armSync: Promise<number>; tip: string | null; accept: Promise<"duplicate" | "recorded">; alarm: Promise<void>; nextWake: () => number | null; }>

lsRefsRequest()function

Section titled “lsRefsRequest()”
Signature
function lsRefsRequest(): Uint8Array;

The protocol-v2 ls-refs request body.

Returns

Section titled “Returns”

Uint8Array

parseLsRefs()function

Section titled “parseLsRefs()”
Signature
function parseLsRefs(response): object[];

Parse an ls-refs response into refs.

Parameters

Section titled “Parameters”
Parameter Type
response Uint8Array

Returns

Section titled “Returns”

object[]

signStandardWebhook()function

Section titled “signStandardWebhook()”
Signature
function signStandardWebhook(secret, id, timestamp, body): Promise<string>;

The Standard Webhooks webhook-signature value for one delivery.

Parameters

Section titled “Parameters”
Parameter Type
secret string
id string
timestamp number
body string

Returns

Section titled “Returns”

Promise<string>

webhookHeaders()function

Section titled “webhookHeaders()”
Signature
function webhookHeaders(
  secret,
  id,
  type,
  timestamp,
  body,
): Promise<Record<string, string>>;

Headers for one signed delivery: Standard Webhooks plus X-Hub-Signature-256.

Parameters

Section titled “Parameters”
Parameter Type
secret string
id string
type string
timestamp number
body string

Returns

Section titled “Returns”

Promise<Record<string, string>>