sailfork / t3code-github / .repos/ alchemy-effect/ packages/ git/ src/ Api/ Refs.ts

/**
 * The `refs` group: ref reads and transactional (CAS) writes (DESIGN.md §5).
 *
 * Ref names contain `/`, so the single-ref endpoints address the ref via
 * the `name` query parameter, not a path segment.
 */
import * as HttpApiEndpoint from "effect/http-api/HttpApiEndpoint";
import * as HttpApiGroup from "effect/http-api/HttpApiGroup";
import * as HttpApiSchema from "effect/http-api/HttpApiSchema";
import * as Schema from "effect/Schema";
import {
  ObjectNotFound,
  Oid,
  ReadOnlyRepo,
  Ref,
  RefConflict,
  RefName,
  RefNotFound,
  RepoNotFound,
  RepoPath,
  PushDenied,
} from "./Schema.ts";

/** Lists refs, optionally filtered by prefix (e.g. `refs/heads/`). */
export const ListRefs = HttpApiEndpoint.get("list", "/repos/:owner/:repo/refs", {
  params: RepoPath,
  query: Schema.Struct({
    /** Filter by prefix, e.g. `refs/heads/`. */
    prefix: Schema.optional(Schema.String),
  }),
  success: Schema.Struct({
    /** The default branch's full ref name, `null` on an unborn repo. */
    head: Schema.NullOr(Schema.String),
    refs: Schema.Array(Ref),
  }),
  error: [RepoNotFound],
});

/** Reads one ref by full name (`?name=refs/heads/main`). */
export const GetRef = HttpApiEndpoint.get("get", "/repos/:owner/:repo/ref", {
  params: RepoPath,
  query: Schema.Struct({ name: RefName }),
  success: Ref,
  error: [RepoNotFound, RefNotFound],
});

/** Writes one ref with CAS semantics. */
export const UpdateRef = HttpApiEndpoint.put("update", "/repos/:owner/:repo/ref", {
  params: RepoPath,
  query: Schema.Struct({ name: RefName }),
  payload: Schema.Struct({
    newOid: Oid,
    /**
     * CAS token: current oid the ref must hold. `null` = the ref must
     * not exist (create). Absent = unconditional write.
     */
    expectedOid: Oid.pipe(Schema.NullOr, Schema.optional),
  }),
  success: Ref,
  error: [PushDenied, RepoNotFound, RefConflict, ObjectNotFound, ReadOnlyRepo],
});

/** Deletes one ref with CAS semantics. */
export const RemoveRef = HttpApiEndpoint.delete("remove", "/repos/:owner/:repo/ref", {
  params: RepoPath,
  query: Schema.Struct({ name: RefName }),
  payload: Schema.Struct({
    /** CAS token: current oid the ref must hold. Absent = unconditional. */
    expectedOid: Schema.optional(Oid),
  }),
  success: HttpApiSchema.NoContent,
  error: [PushDenied, RepoNotFound, RefNotFound, RefConflict, ReadOnlyRepo],
});

/** The `refs` group, mounted at `/api/v1`. */
export class Refs extends HttpApiGroup.make("refs")
  .add(ListRefs, GetRef, UpdateRef, RemoveRef)
  .prefix("/api/v1") {}