a collection of lightweight TypeScript packages for AT Protocol, the protocol powering Bluesky
atproto
bluesky
typescript
npm
docs: flesh out utilities README
+96
-11
+16
-1
packages/utilities/car/README.md
+16
-1
packages/utilities/car/README.md
···
1
1
# @atcute/car
2
2
3
-
content-addressable archive (CAR) reader for AT Protocol.
3
+
content-addressable archive (CAR) codec for AT Protocol.
4
4
5
5
```sh
6
6
npm install @atcute/car
···
64
64
// ^? CarEntry { cid: CidLink {}, bytes: Uint8Array {}, ... }
65
65
}
66
66
```
67
+
68
+
### writing
69
+
70
+
```ts
71
+
import { writeCarStream } from '@atcute/car';
72
+
73
+
const blocks = async function* () {
74
+
yield { cid: commitCid.bytes, data: commitBytes };
75
+
yield { cid: nodeCid.bytes, data: nodeBytes };
76
+
};
77
+
78
+
for await (const chunk of writeCarStream([rootCid], blocks())) {
79
+
stream.write(chunk);
80
+
}
81
+
```
+4
-1
packages/utilities/cbor/README.md
+4
-1
packages/utilities/cbor/README.md
···
32
32
### decoding
33
33
34
34
```ts
35
-
import { decode } from '@atcute/cbor';
35
+
import { decode, decodeFirst } from '@atcute/cbor';
36
36
37
37
const record = decode(cborBytes);
38
38
// -> { $type: 'app.bsky.feed.post', ... }
39
+
40
+
// decode from a buffer containing multiple values
41
+
const [value, remainder] = decodeFirst(cborBytes);
39
42
```
40
43
41
44
## notes
+23
packages/utilities/cid/README.md
+23
packages/utilities/cid/README.md
···
24
24
25
25
// create from raw data
26
26
const rawCid = await CID.create(0x55, rawBytes);
27
+
28
+
// create an empty CID (zero-length digest)
29
+
const empty = CID.createEmpty(0x71);
27
30
```
28
31
29
32
### parsing CIDs
···
62
65
63
66
CID.equals(cidA, cidB); // true if same content hash
64
67
```
68
+
69
+
### CidLink wrapper
70
+
71
+
for JSON serialization compatible with atproto's data model:
72
+
73
+
```ts
74
+
import { toCidLink, fromCidLink, isCidLink } from '@atcute/cid';
75
+
76
+
// convert Cid to CidLink (has $link property)
77
+
const link = toCidLink(cid);
78
+
// -> { $link: "bafyrei..." }
79
+
80
+
// convert back to Cid
81
+
const cid = fromCidLink(link);
82
+
83
+
// type guard
84
+
if (isCidLink(value)) {
85
+
console.log(value.$link);
86
+
}
87
+
```
+2
-2
packages/utilities/crypto/lib/types.ts
+2
-2
packages/utilities/crypto/lib/types.ts
···
8
8
readonly jwtAlg: string;
9
9
10
10
/**
11
-
* Verifies a signature against a provided data
11
+
* Verifies a signature against provided data
12
12
*/
13
13
verify(sig: Uint8Array, data: Uint8Array, options?: VerifyOptions): Promise<boolean>;
14
14
···
19
19
* - `jwk`: serialized to JWK (JSON Web Key)
20
20
* - `multikey`: serialized to multikey string
21
21
* - `raw`: as raw bytes
22
-
* - `rawHex` serialized to base16 string
22
+
* - `rawHex`: serialized to base16 string
23
23
*/
24
24
exportPublicKey(format: 'did'): Promise<DidKeyString>;
25
25
exportPublicKey(format: 'jwk'): Promise<JsonWebKey>;
+35
packages/utilities/repo/README.md
+35
packages/utilities/repo/README.md
···
64
64
repo.missingBlocks;
65
65
// ^? []
66
66
```
67
+
68
+
### verifying records
69
+
70
+
verify a record's inclusion in a repository with optional signature verification:
71
+
72
+
```ts
73
+
import { verifyRecord } from '@atcute/repo';
74
+
75
+
const { cid, record } = await verifyRecord({
76
+
collection: 'app.bsky.feed.post',
77
+
rkey: '3lprcc55bb222',
78
+
carBytes: carBytes,
79
+
// optional: verify commit signature
80
+
publicKey: key,
81
+
// optional: verify DID matches
82
+
did: 'did:plc:...',
83
+
});
84
+
```
85
+
86
+
### transform streams
87
+
88
+
for piping repository data through a transform:
89
+
90
+
```ts
91
+
import { repoEntryTransform } from '@atcute/repo';
92
+
93
+
const { readable, writable } = repoEntryTransform();
94
+
95
+
// pipe CAR data in, get RepoEntry objects out
96
+
response.body.pipeTo(writable);
97
+
98
+
for await (const entry of readable) {
99
+
console.log(entry.collection, entry.rkey);
100
+
}
101
+
```
+1
-1
packages/utilities/tid/README.md
+1
-1
packages/utilities/tid/README.md
+1
-1
packages/utilities/tid/package.json
+1
-1
packages/utilities/tid/package.json
+14
-5
packages/utilities/varint/README.md
+14
-5
packages/utilities/varint/README.md
···
7
7
```
8
8
9
9
```ts
10
-
import { encode } from '@atcute/varint';
10
+
import { encode, decode, encodingLength } from '@atcute/varint';
11
11
12
+
// encoding
12
13
const encoded: number[] = [];
13
-
const encodedLength = encode(420, encoded);
14
+
const bytesWritten = encode(420, encoded);
15
+
// -> encoded: [164, 3]
16
+
// -> bytesWritten: 2
17
+
18
+
// decoding
19
+
const [num, bytesRead] = decode(encoded);
20
+
// -> num: 420
21
+
// -> bytesRead: 2
14
22
15
-
console.log(encoded, encodedLength);
16
-
// -> encoded: Array(2) [164, 3]
17
-
// -> encodedLength: 2
23
+
// check encoding length beforehand
24
+
encodingLength(420); // -> 2
25
+
encodingLength(16383); // -> 2
26
+
encodingLength(16384); // -> 3
18
27
```