@repome/sdk 0.1.2

package/README.md

@@ -0,0 +1,103 @@
+# @repome/sdk
+
+Use repome as a git SDK — write files, commit, and push from any JavaScript
+runtime with no clone required.
+
+## Porcelain API
+
+```ts
+import { repome } from '@repome/sdk'
+
+const git = await repome('acme/my-repo', {
+  token: process.env.REPOME_TOKEN!,
+})
+
+await git.add('src/main.ts', sourceCode)
+await git.add('README.md', readmeText)
+
+const commit = await git.commit('feat: generated output')
+console.log(commit.sha) // a1b2c3d4...
+console.log(commit.url) // https://api.repome.sh/acme/my-repo/commit/a1b2c3d
+```
+
+`repome(slug, options)` returns a `GitRepo` bound to one repo. The repo is
+created automatically if it does not exist. Files staged with `add()` are
+held in memory and pushed as a single atomic commit when you call
+`commit()`.
+
+```ts
+interface GitRepo {
+  add(path: string, content: string | Uint8Array): Promise<void>
+  remove(path: string): Promise<void>
+  commit(message: string, options?: CommitOptions): Promise<Commit>
+  read(path: string, ref?: string): Promise<Blob>
+  ls(ref?: string, options?: LsOptions): Promise<TreeEntry[]>
+  log(options?: LogOptions): Promise<Commit[]>
+}
+```
+
+`add()` and `remove()` accumulate in memory; the next `commit()` packages
+both into one atomic request. `read()` returns
+`{ content: string, bytes: Uint8Array, sha }` — use `bytes` for binary
+content. `ls()` returns a flat, recursive listing by default; pass
+`{ recursive: false }` for a one-level directory walk.
+
+Use `repome.ephemeral()` when you need a no-account repo for SDK writes:
+
+```ts
+const git = await repome.ephemeral({ ttl: '24h' })
+await git.add('README.md', '# hello')
+await git.commit('initial')
+
+console.log(git.remote)
+console.log(git.expiresAt)
+```
+
+Anonymous repos currently support the SDK control-plane path. Plain `git push`
+to an anonymous magic endpoint is not part of this SDK slice.
+
+## Low-level oRPC client
+
+`createClient({ baseUrl, apiKey })` returns the typed oRPC client over the
+raw contract. Use it when you need a procedure that isn't on `GitRepo`
+(e.g. `keys.*`, `repos.list`, `orgs.*`).
+
+```ts
+import { createClient } from '@repome/sdk'
+
+const client = createClient({
+  baseUrl: 'https://api.repome.sh',
+  apiKey: process.env.REPOME_API_KEY!,
+})
+
+const { items } = await client.repos.list({ orgSlug: 'acme' })
+```
+
+API keys must use the `rpme_` prefix and are sent as
+`Authorization: Bearer <key>`. Create keys with
+`repome keys create <name> --scope repos:write`; repeat `--scope` for
+additional access.
+
+## Smoke test
+
+`scripts/smoke.ts` drives the full porcelain surface (ensure, add, commit,
+read, ls, remove, log, commit-view URL) against a live Worker and cleans up
+the test repo on the way out.
+
+```bash
+# Local dev (portless)
+export REPOME_SERVER_URL=https://api.repome.test
+export REPOME_API_KEY=$(repome auth token)
+vp run @repome/sdk#smoke
+
+# Skip cleanup to inspect the resulting repo
+REPOME_SMOKE_KEEP=1 vp run @repome/sdk#smoke
+
+# Pin the repo name (otherwise sdk-smoke-<random>)
+REPOME_SMOKE_NAME=sdk-smoke vp run @repome/sdk#smoke
+```
+
+Inputs: `REPOME_API_KEY` (required; needs `repos:read` + `repos:write`),
+`REPOME_SERVER_URL` (default `https://api.repome.sh`),
+`REPOME_SMOKE_ORG` (default: active org from `me.get`),
+`REPOME_SMOKE_NAME`, `REPOME_SMOKE_KEEP=1`.