Repos

Repos are created programmatically and referenced by slug or stable ID.

Quickstart

import { Client } from "@githosted/sdk";

const client = new Client();

// Create a repo
const repo = await client.createRepo("my-new-project");
console.log(repo.id); // "rp_8f3k2m1q9t6w4z7c5n2h"

// Write immediately — no setup needed
await repo.write("README.md", "# My Project", { message: "Initial commit" });

Referencing Repos

By slug

const repo = client.repo("my-project");

By stable ID

const repo = client.repo({ id: "rp_8f3k2m1q9t6w4z7c5n2h" });

Store IDs, not slugs. Repo IDs (rp_ prefix) are globally unique and stable even if the repo is renamed. Slugs are human-readable but can change.

API Reference

`client.createRepo(name, options?)`

Create a new repo in a workspace. Returns a Repo handle with a stable ID.

const repo = await client.createRepo("session-data", {
  workspaceRef: "my-workspace",
});

// The repo is immediately ready for reads and writes
console.log(repo.id);           // "rp_..."
console.log(repo.info?.slug);   // "session-data"

`client.repo(ref)`

Get a handle to an existing repo. Does not make a network call — the handle is created locally.

// These are equivalent ways to get a repo handle
const repo = client.repo("my-project");
const repo = client.repo({ id: "rp_8f3k2m1q9t6w4z7c5n2h" });

Repo IDs

Property	Value
Format	`rp_` prefix + 20-char NanoID (`0-9a-z`)
Unique	Globally unique across all workspaces
Stable	Doesn’t change if repo is renamed

`client.listRepos(options?)`

List all repos in the workspace. Requires a workspace token (gw_).

const result = await client.listRepos();
for (const repo of result.repos) {
  console.log(`${repo.id} ${repo.slug} (${repo.defaultBranch})`);
}

// Paginated
const page = await client.listRepos({ pageSize: 10 });
const next = await client.listRepos({ pageToken: page.nextPageToken });

Common Patterns

Store repo ID in your database

// When creating a project for a user
const repo = await client.createRepo(`${userId}-${projectName}`);
await db.users.update(userId, { repoId: repo.id });

// Later — resume from stored ID
const repoId = await db.users.get(userId).repoId;
const repo = client.repo({ id: repoId });