Get started

Quickstart

Next release: this page describes techne-sdk/auth/react and techne-sdk/types, which are not in techne-sdk 0.3.4 yet. With techne-sdk 0.3 today shows the released API.

Install, sign a person in, read records, write records. In React, in plain TypeScript, or from an agent.

With techne-sdk 0.3 today

With techne-sdk 0.3.4 from npm, sign in, write and read like this.

Name the types your app writes in types, the same in signIn, restore and clientMetadata. The sign-in then asks for a repo: scope for each, your app's own private space and the platform's reads, and nothing more. Permissions lists every scope.

put(techne, records)
From techne-sdk/put. A record of a public type names no space and goes to their repo. Any other record is private and must name its space: your app's space below, or their own at://{did}/pub.techne.draft.space.personal/self. One with no space is refused.
appSpace(did, clientId)
Your app's private space for this person. Only your app reads it.

Give every record a createdAt: put derives the record key from it. Your app's space takes any type but the platform's own pub.techne record types.

Install

One package for React and plain TypeScript. Agents add the MCP server instead.

techne-sdk/auth/react is the sign-in provider and every read hook; techne-sdk/react is the hooks alone. React itself is your app's.

Log in

"Sign in with Techne" works like Sign in with Google. Your app is its own atproto OAuth client. The person signs in at their own PDS. They consent to your app and the scopes it asks for. They do not consent to the platform.

With no handle they start at techne.town, which asks who they are. A bare name like yourname means yourname.techne.town; a handle from any other PDS works as it is.

Then connect(session, TECHNE_PLATFORM_DID). TECHNE_PLATFORM_DID is the platform's service DID, did:web:techne.computer, exported by techne-sdk/auth. Until they sign in, the provider reads public records anonymously.

clientId
The address of your app's client metadata on your domain, such as https://your.app/oauth-client-metadata.json. clientMetadata() writes the document. On localhost leave it out. The SDK then uses atproto's loopback client, so nothing needs hosting.
session
Their OAuth session with your app. It holds their DID and a fetchHandler that signs requests as them. It is kept in the browser and refreshed for you.
signUp
For someone with no account yet, signUp opens techne.town's create-account screen, then comes back signed in.

Inside the provider, useTechne() is connected for them once they sign in. useAuthStatus() says 'restoring', 'signed-in' or 'signed-out'; useSignOut() signs them out.

Read

A read is a query. It says which records you want and in what order. Place.query builds one for places.

Anyone may read public records. Records in a space come back only to people its read policy admits.

The full method is query.listRecords →
Every call is in the Reference →
pub.techne.draft.place
A record type (an NSID). Its fields are at place.draft.techne.pub.
at://…
A record's address. It names the repo, the type and the key.

Inside <TechneProvider>. It refetches and caches like any TanStack Query read.

Write

A write lands in the person's own repo on their PDS; the SDK sends it there with the person's own session.

A record in a space is read only by the space's readers.

space
Where a private record counts, at://{owner}/{spaceType}/{key}.
circleDid
The DID of the collective whose members read the post; it is the circle space's key.
pending
Written, not yet indexed. Show it as pending until it is.

useTechne() is the same techne as on the SDK tab, so put takes the same records and spaces.