veyce 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +246 -2
- package/dist/cli.js +262 -0
- package/dist/index.cjs +196 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +134 -0
- package/dist/index.d.ts +134 -0
- package/dist/index.js +159 -0
- package/dist/index.js.map +1 -0
- package/dist/react.cjs +141 -0
- package/dist/react.cjs.map +1 -0
- package/dist/react.d.cts +63 -0
- package/dist/react.d.ts +63 -0
- package/dist/react.js +115 -0
- package/dist/react.js.map +1 -0
- package/package.json +79 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mohamed Salah
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,247 @@
|
|
|
1
|
-
#
|
|
1
|
+
# veyce
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**The JavaScript client for [veyce](https://veyce.vercel.app) — a free avatar
|
|
4
|
+
API that serves GTA VI character art as profile pictures.** No API key, no
|
|
5
|
+
sign-up, permissive CORS. Give it an email or username and you get the same
|
|
6
|
+
face back for that person every time.
|
|
7
|
+
|
|
8
|
+
<p>
|
|
9
|
+
<img src="https://veyce.vercel.app/api/gta-vi?seed=ada%40example.com&size=96&format=png" width="72" height="72" alt="avatar for ada@example.com" />
|
|
10
|
+
<img src="https://veyce.vercel.app/api/gta-vi?seed=grace%40example.com&size=96&format=png" width="72" height="72" alt="avatar for grace@example.com" />
|
|
11
|
+
<img src="https://veyce.vercel.app/api/gta-vi?seed=linus&size=96&format=png" width="72" height="72" alt="avatar for linus" />
|
|
12
|
+
<img src="https://veyce.vercel.app/api/gta-vi?seed=alan%40turing.dev&size=96&format=png" width="72" height="72" alt="avatar for alan@turing.dev" />
|
|
13
|
+
<img src="https://veyce.vercel.app/api/gta-vi?seed=42&size=96&format=png" width="72" height="72" alt="avatar for 42" />
|
|
14
|
+
<img src="https://veyce.vercel.app/api/gta-vi?seed=noah&size=96&format=png" width="72" height="72" alt="avatar for noah" />
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<sub>These images are live, loaded straight from the veyce API, one per seed:
|
|
18
|
+
<code>ada@example.com</code>, <code>grace@example.com</code>, <code>linus</code>,
|
|
19
|
+
<code>alan@turing.dev</code>, <code>42</code>, <code>noah</code>.</sub>
|
|
20
|
+
|
|
21
|
+
## What this package is
|
|
22
|
+
|
|
23
|
+
`veyce` doesn't contain any images and doesn't generate any. It's a small
|
|
24
|
+
(~2 KB gzipped, zero-dependency) wrapper around the hosted veyce API at
|
|
25
|
+
`https://veyce.vercel.app`, which holds a curated library of GTA VI character
|
|
26
|
+
images (Jason, Lucia, Cal, Boobie, Raul, Real Dimez and more) and serves them
|
|
27
|
+
resized and cropped to a circle or square on request.
|
|
28
|
+
|
|
29
|
+
The package gives you:
|
|
30
|
+
|
|
31
|
+
- **A URL builder.** `url()` and `srcSet()` are plain string functions with no
|
|
32
|
+
network calls, so they're safe to use in render functions, templates and
|
|
33
|
+
server components.
|
|
34
|
+
- **Fetch helpers.** Download bytes, get a `data:` URI, or check which image a
|
|
35
|
+
seed lands on with a `HEAD` request.
|
|
36
|
+
- **Offline seed picks.** Fetch the image index once, then map seeds to images
|
|
37
|
+
locally and get the same answer the API would give.
|
|
38
|
+
- **A React `<Avatar>`** with `srcSet`, lazy loading and fixed dimensions so
|
|
39
|
+
the layout doesn't shift.
|
|
40
|
+
- **A CLI**: `npx veyce get --seed you@example.com`.
|
|
41
|
+
|
|
42
|
+
It runs in browsers, Node 18+, Bun, Deno and edge runtimes, and ships ESM, CJS
|
|
43
|
+
and TypeScript types.
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm install veyce
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Picking an avatar
|
|
50
|
+
|
|
51
|
+
There are two ways to ask for an image, and you can combine them.
|
|
52
|
+
|
|
53
|
+
**By seed.** Pass any string (an email, username, uuid or number). The same
|
|
54
|
+
seed always gets the same image, and a seed never 404s:
|
|
55
|
+
|
|
56
|
+
| seed | | seed | |
|
|
57
|
+
| --- | --- | --- | --- |
|
|
58
|
+
| `ada@example.com` | <img src="https://veyce.vercel.app/api/gta-vi?seed=ada%40example.com&size=96&format=png" width="48" height="48" alt="" /> | `linus` | <img src="https://veyce.vercel.app/api/gta-vi?seed=linus&size=96&format=png" width="48" height="48" alt="" /> |
|
|
59
|
+
| `grace@example.com` | <img src="https://veyce.vercel.app/api/gta-vi?seed=grace%40example.com&size=96&format=png" width="48" height="48" alt="" /> | `42` | <img src="https://veyce.vercel.app/api/gta-vi?seed=42&size=96&format=png" width="48" height="48" alt="" /> |
|
|
60
|
+
|
|
61
|
+
**By id.** Every image has a short readable id. Ask for one and you get exactly
|
|
62
|
+
that image, or a 404 if the id doesn't exist:
|
|
63
|
+
|
|
64
|
+
| `jason-mask` | `lucia-mask` | `raul` | `boobie-ike` | `real-dimez` |
|
|
65
|
+
| --- | --- | --- | --- | --- |
|
|
66
|
+
| <img src="https://veyce.vercel.app/api/gta-vi/jason-mask/96?format=png" width="56" height="56" alt="jason-mask" /> | <img src="https://veyce.vercel.app/api/gta-vi/lucia-mask/96?format=png" width="56" height="56" alt="lucia-mask" /> | <img src="https://veyce.vercel.app/api/gta-vi/raul/96?format=png" width="56" height="56" alt="raul" /> | <img src="https://veyce.vercel.app/api/gta-vi/boobie-ike/96?format=png" width="56" height="56" alt="boobie-ike" /> | <img src="https://veyce.vercel.app/api/gta-vi/real-dimez/96?format=png" width="56" height="56" alt="real-dimez" /> |
|
|
67
|
+
|
|
68
|
+
Browse every id in the [gallery](https://veyce.vercel.app/gallery), or call
|
|
69
|
+
`avatars.list()`.
|
|
70
|
+
|
|
71
|
+
## Quick start
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import { createAvatars } from "veyce";
|
|
75
|
+
|
|
76
|
+
const avatars = createAvatars({
|
|
77
|
+
// baseUrl defaults to https://veyce.vercel.app
|
|
78
|
+
defaults: { collection: "gta-vi", size: 96 },
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
avatars.url({ seed: "ada@example.com" });
|
|
82
|
+
// https://veyce.vercel.app/api/gta-vi?seed=ada%40example.com&size=96
|
|
83
|
+
|
|
84
|
+
avatars.url({ id: "raul", square: true });
|
|
85
|
+
// https://veyce.vercel.app/api/gta-vi?id=raul&size=96&square=true
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
```html
|
|
89
|
+
<img src="https://veyce.vercel.app/api/gta-vi?seed=ada%40example.com&size=96" width="96" height="96" alt="" />
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
`url()` and `srcSet()` are pure string work — no network — so they are safe in
|
|
93
|
+
render functions, templates and server components.
|
|
94
|
+
|
|
95
|
+
## Seed vs id
|
|
96
|
+
|
|
97
|
+
| you pass | you get | unknown value |
|
|
98
|
+
| --- | --- | --- |
|
|
99
|
+
| `seed` | the image the seed hashes onto | never happens — every seed lands somewhere |
|
|
100
|
+
| `id` | that exact image | `404` |
|
|
101
|
+
| `id` + `seed` | the id if it exists, otherwise the seed's image | falls back to the seed |
|
|
102
|
+
| neither | a random image (`no-store`) | — |
|
|
103
|
+
|
|
104
|
+
Seeds are always sent as `?seed=`, so a seed that looks like an id (`raul`), a
|
|
105
|
+
size (`1234`) or a crop (`square`) is still treated as a seed.
|
|
106
|
+
|
|
107
|
+
> The mapping is stable for a fixed library. Adding or removing images in a
|
|
108
|
+
> collection reshuffles which seed lands where. If a user should keep their
|
|
109
|
+
> face forever, pin it — see `resolve()` below.
|
|
110
|
+
|
|
111
|
+
## API
|
|
112
|
+
|
|
113
|
+
### `createAvatars(config)`
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
createAvatars({
|
|
117
|
+
baseUrl?: string; // default https://veyce.vercel.app; a trailing /api is fine
|
|
118
|
+
defaults?: AvatarOptions; // merged into every call
|
|
119
|
+
fetch?: typeof fetch; // custom fetch for tests/proxies
|
|
120
|
+
}): AvatarClient
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### `AvatarOptions`
|
|
124
|
+
|
|
125
|
+
| option | type | default | |
|
|
126
|
+
| --- | --- | --- | --- |
|
|
127
|
+
| `seed` | `string \| number` | — | Anything. Always resolves. |
|
|
128
|
+
| `id` | `string` | — | Exact image id. |
|
|
129
|
+
| `collection` | `string` | all | Narrow to one collection. |
|
|
130
|
+
| `size` | `number` | `80` | 8–2160, clamped. Never upscaled past the source. |
|
|
131
|
+
| `crop` | `square \| portrait \| landscape \| phone \| tablet \| ultrawide` | `square` | Falls back to `square` if the image lacks it. |
|
|
132
|
+
| `fit` | `cover \| full` | `cover` | `full` keeps the aspect ratio, no mask. |
|
|
133
|
+
| `square` | `boolean` | `false` | Square corners instead of a circle. |
|
|
134
|
+
| `format` | `webp \| png \| jpeg` | `webp` | |
|
|
135
|
+
| `background` | hex | `#ffffff` | Corner fill for circle-masked JPEGs. |
|
|
136
|
+
|
|
137
|
+
### Client methods
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
avatars.url(options) // string
|
|
141
|
+
avatars.srcSet(options) // "url 1x, url 2x, url 3x"
|
|
142
|
+
await avatars.fetch(options) // { bytes: Uint8Array, contentType, info }
|
|
143
|
+
await avatars.dataUri(options) // "data:image/webp;base64,..."
|
|
144
|
+
await avatars.resolve(options) // AvatarInfo, via HEAD — no image download
|
|
145
|
+
await avatars.list(collection?) // the library index
|
|
146
|
+
avatars.pick(seed, index) // offline seed -> photo, same answer as the API
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
`AvatarInfo` tells you what the API picked:
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
{ collection: "gta-vi", id: "cal", crop: "square", size: 96,
|
|
153
|
+
match: "seed", // "id" | "seed" | "random"
|
|
154
|
+
url: "https://veyce.vercel.app/api/gta-vi?id=cal" } // stable, id-addressed
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
#### Pinning a seeded avatar
|
|
158
|
+
|
|
159
|
+
Give a new user a seeded face, then store the id so it survives library changes:
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
const { id } = await avatars.resolve({ seed: user.email });
|
|
163
|
+
await db.users.update(user.id, { avatarId: id });
|
|
164
|
+
|
|
165
|
+
// later — exact id, with the email as a safety net if that image is ever removed
|
|
166
|
+
avatars.url({ id: user.avatarId, seed: user.email });
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
#### Offline picks
|
|
170
|
+
|
|
171
|
+
Fetch the index once (cache it), then map seeds locally — useful for batch
|
|
172
|
+
jobs or when you want ids without one request per user:
|
|
173
|
+
|
|
174
|
+
```ts
|
|
175
|
+
const index = await avatars.list("gta-vi");
|
|
176
|
+
const photo = avatars.pick("ada@example.com", index); // { id: "cal", ... }
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### Standalone helpers
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
import { avatarUrl, avatarSrcSet, hashSeed, pick, AvatarError } from "veyce";
|
|
183
|
+
|
|
184
|
+
avatarUrl("https://veyce.vercel.app", { seed: "ada" });
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Failed requests throw `AvatarError` with `.status` (404 unknown id/collection,
|
|
188
|
+
409 id in several collections) and the parsed `.body`.
|
|
189
|
+
|
|
190
|
+
## React
|
|
191
|
+
|
|
192
|
+
```tsx
|
|
193
|
+
import { Avatar, AvatarProvider, useAvatarUrl } from "veyce/react";
|
|
194
|
+
|
|
195
|
+
export function App() {
|
|
196
|
+
return (
|
|
197
|
+
<AvatarProvider defaults={{ collection: "gta-vi" }}>
|
|
198
|
+
<Avatar seed="ada@example.com" size={48} />
|
|
199
|
+
<Avatar id={user.avatarId} seed={user.email} size={64} square className="rounded-lg" />
|
|
200
|
+
</AvatarProvider>
|
|
201
|
+
);
|
|
202
|
+
}
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
`<Avatar>` renders a plain `<img>` with `width`/`height` set (no layout shift),
|
|
206
|
+
`loading="lazy"`, `decoding="async"` and a 1x/2x/3x `srcSet` (`hiDpi={false}`
|
|
207
|
+
to turn it off). Every other `<img>` prop passes through; the HTML `id`
|
|
208
|
+
attribute is `htmlId` because `id` is the image id. You can also pass
|
|
209
|
+
`baseUrl` straight to `<Avatar>` and skip the provider — or omit it entirely to
|
|
210
|
+
use https://veyce.vercel.app.
|
|
211
|
+
|
|
212
|
+
The entry is marked `"use client"`, so it works from Next.js server components.
|
|
213
|
+
If you only need the URL in a server component, call `avatarUrl()` from the
|
|
214
|
+
main entry instead.
|
|
215
|
+
|
|
216
|
+
## CLI
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
npx veyce url --seed ada@example.com -c gta-vi --size 96
|
|
220
|
+
npx veyce get --seed ada@example.com --size 256 -o ada.webp
|
|
221
|
+
npx veyce resolve --seed ada@example.com
|
|
222
|
+
npx veyce list --collection gta-vi
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Requests go to `https://veyce.vercel.app` unless you pass `--base URL` or set
|
|
226
|
+
`VEYCE_URL`. `veyce --help` lists every flag.
|
|
227
|
+
|
|
228
|
+
## Self-hosting
|
|
229
|
+
|
|
230
|
+
The veyce service serves whatever images sit in its
|
|
231
|
+
`public/avatar/<collection>/<id>/` folders. If you run your own copy with your
|
|
232
|
+
own images, point the client at it with `createAvatars({ baseUrl })`,
|
|
233
|
+
`<Avatar baseUrl>`, or `--base` / `VEYCE_URL` on the CLI. Everything above
|
|
234
|
+
works the same way; only the collections and ids change.
|
|
235
|
+
|
|
236
|
+
## License
|
|
237
|
+
|
|
238
|
+
MIT for the package code; see [LICENSE](LICENSE).
|
|
239
|
+
|
|
240
|
+
The package itself contains no images. The avatars served by
|
|
241
|
+
`https://veyce.vercel.app` are GTA VI artwork owned by Rockstar Games /
|
|
242
|
+
Take-Two Interactive, not by this package or its author. Check the rights
|
|
243
|
+
holder's terms before storing or redistributing them, and use your own images
|
|
244
|
+
on a self-hosted service if you need avatars you control.
|
|
245
|
+
|
|
246
|
+
veyce is an independent project and is not affiliated with or endorsed by
|
|
247
|
+
Rockstar Games, Take-Two Interactive, DiceBear or Gravatar.
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// src/cli.ts
|
|
4
|
+
import { writeFile } from "fs/promises";
|
|
5
|
+
import { parseArgs } from "util";
|
|
6
|
+
|
|
7
|
+
// src/index.ts
|
|
8
|
+
var DEFAULT_BASE_URL = "https://veyce.vercel.app";
|
|
9
|
+
var MIN_SIZE = 8;
|
|
10
|
+
var MAX_SIZE = 2160;
|
|
11
|
+
var DEFAULT_SIZE = 80;
|
|
12
|
+
var FORMATS = ["webp", "png", "jpeg"];
|
|
13
|
+
var AvatarError = class extends Error {
|
|
14
|
+
constructor(message, status, body) {
|
|
15
|
+
super(message);
|
|
16
|
+
this.name = "AvatarError";
|
|
17
|
+
this.status = status;
|
|
18
|
+
this.body = body;
|
|
19
|
+
}
|
|
20
|
+
};
|
|
21
|
+
function hashSeed(seed) {
|
|
22
|
+
const value = String(seed);
|
|
23
|
+
let hash = 0;
|
|
24
|
+
for (let i = 0; i < value.length; i += 1) {
|
|
25
|
+
hash = (hash << 5) - hash + value.charCodeAt(i);
|
|
26
|
+
hash |= 0;
|
|
27
|
+
}
|
|
28
|
+
return Math.abs(hash) || 1;
|
|
29
|
+
}
|
|
30
|
+
function pick(seed, photos) {
|
|
31
|
+
if (!photos.length) return void 0;
|
|
32
|
+
return photos[hashSeed(seed) % photos.length];
|
|
33
|
+
}
|
|
34
|
+
function clampSize(size) {
|
|
35
|
+
if (!Number.isFinite(size)) return DEFAULT_SIZE;
|
|
36
|
+
return Math.min(MAX_SIZE, Math.max(MIN_SIZE, Math.round(size)));
|
|
37
|
+
}
|
|
38
|
+
function apiRoot(baseUrl) {
|
|
39
|
+
const trimmed = (baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
|
|
40
|
+
return /\/api$/.test(trimmed) ? trimmed : `${trimmed}/api`;
|
|
41
|
+
}
|
|
42
|
+
function normalizeHex(value) {
|
|
43
|
+
const hex = value.replace(/^#/, "");
|
|
44
|
+
return /^([0-9a-f]{3}|[0-9a-f]{6})$/i.test(hex) ? hex.toLowerCase() : null;
|
|
45
|
+
}
|
|
46
|
+
function avatarUrl(baseUrl, options = {}) {
|
|
47
|
+
const root = apiRoot(baseUrl);
|
|
48
|
+
const path = options.collection ? `${root}/${encodeURIComponent(options.collection)}` : root;
|
|
49
|
+
const query = new URLSearchParams();
|
|
50
|
+
if (options.id !== void 0 && options.id !== "") query.set("id", options.id);
|
|
51
|
+
if (options.seed !== void 0 && options.seed !== "") query.set("seed", String(options.seed));
|
|
52
|
+
if (options.size !== void 0) query.set("size", String(clampSize(options.size)));
|
|
53
|
+
if (options.crop) query.set("crop", options.crop);
|
|
54
|
+
if (options.fit && options.fit !== "cover") query.set("fit", options.fit);
|
|
55
|
+
if (options.square) query.set("square", "true");
|
|
56
|
+
if (options.format && options.format !== "webp") query.set("format", options.format);
|
|
57
|
+
if (options.background) {
|
|
58
|
+
const hex = normalizeHex(options.background);
|
|
59
|
+
if (!hex) throw new TypeError(`veyce: invalid background "${options.background}".`);
|
|
60
|
+
query.set("bg", hex);
|
|
61
|
+
}
|
|
62
|
+
const qs = query.toString();
|
|
63
|
+
return qs ? `${path}?${qs}` : path;
|
|
64
|
+
}
|
|
65
|
+
function avatarSrcSet(baseUrl, options = {}, densities = [1, 2, 3]) {
|
|
66
|
+
const size = options.size ?? DEFAULT_SIZE;
|
|
67
|
+
const seen = /* @__PURE__ */ new Set();
|
|
68
|
+
return densities.map((density) => ({ density, px: clampSize(size * density) })).filter(({ px }) => seen.has(px) ? false : (seen.add(px), true)).map(({ density, px }) => `${avatarUrl(baseUrl, { ...options, size: px })} ${density}x`).join(", ");
|
|
69
|
+
}
|
|
70
|
+
function readInfo(root, headers, requested) {
|
|
71
|
+
const collection = headers.get("x-photo-collection") ?? "";
|
|
72
|
+
const id = headers.get("x-photo-id") ?? "";
|
|
73
|
+
const match = headers.get("x-photo-match") ?? "id";
|
|
74
|
+
return {
|
|
75
|
+
collection,
|
|
76
|
+
id,
|
|
77
|
+
crop: headers.get("x-photo-crop") ?? "square",
|
|
78
|
+
size: Number(headers.get("x-photo-size") ?? requested),
|
|
79
|
+
match,
|
|
80
|
+
url: avatarUrl(root, { collection, id })
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
async function fail(response) {
|
|
84
|
+
let body;
|
|
85
|
+
let message = response.status === 404 ? "veyce: no image matches (unknown id or collection) \u2014 pass a `seed` to always get one" : response.status === 409 ? "veyce: that id exists in several collections \u2014 pass `collection`" : `veyce: request failed with ${response.status}`;
|
|
86
|
+
try {
|
|
87
|
+
body = await response.json();
|
|
88
|
+
const error = body?.error;
|
|
89
|
+
if (typeof error === "string") message = `veyce: ${error}`;
|
|
90
|
+
} catch {
|
|
91
|
+
}
|
|
92
|
+
throw new AvatarError(message, response.status, body);
|
|
93
|
+
}
|
|
94
|
+
function toBase64(bytes) {
|
|
95
|
+
const B = globalThis.Buffer;
|
|
96
|
+
if (B) return B.from(bytes).toString("base64");
|
|
97
|
+
let binary = "";
|
|
98
|
+
for (let i = 0; i < bytes.length; i += 32768) {
|
|
99
|
+
binary += String.fromCharCode(...bytes.subarray(i, i + 32768));
|
|
100
|
+
}
|
|
101
|
+
return btoa(binary);
|
|
102
|
+
}
|
|
103
|
+
function createAvatars(config = {}) {
|
|
104
|
+
const root = apiRoot(config.baseUrl);
|
|
105
|
+
const defaults = config.defaults ?? {};
|
|
106
|
+
const doFetch = (input, init) => {
|
|
107
|
+
const f = config.fetch ?? globalThis.fetch;
|
|
108
|
+
if (!f) throw new Error("veyce: no global fetch; pass `fetch` in the config.");
|
|
109
|
+
return f(input, init);
|
|
110
|
+
};
|
|
111
|
+
const merge = (options) => ({ ...defaults, ...options });
|
|
112
|
+
const client = {
|
|
113
|
+
baseUrl: root,
|
|
114
|
+
url: (options) => avatarUrl(root, merge(options)),
|
|
115
|
+
srcSet: (options, densities) => avatarSrcSet(root, merge(options), densities),
|
|
116
|
+
async fetch(options) {
|
|
117
|
+
const merged = merge(options);
|
|
118
|
+
const response = await doFetch(avatarUrl(root, merged));
|
|
119
|
+
if (!response.ok) return fail(response);
|
|
120
|
+
const bytes = new Uint8Array(await response.arrayBuffer());
|
|
121
|
+
return {
|
|
122
|
+
bytes,
|
|
123
|
+
contentType: response.headers.get("content-type") ?? `image/${merged.format ?? "webp"}`,
|
|
124
|
+
info: readInfo(root, response.headers, merged.size ?? DEFAULT_SIZE)
|
|
125
|
+
};
|
|
126
|
+
},
|
|
127
|
+
async dataUri(options) {
|
|
128
|
+
const { bytes, contentType } = await client.fetch(options);
|
|
129
|
+
return `data:${contentType};base64,${toBase64(bytes)}`;
|
|
130
|
+
},
|
|
131
|
+
async resolve(options) {
|
|
132
|
+
const merged = merge(options);
|
|
133
|
+
const response = await doFetch(avatarUrl(root, merged), { method: "HEAD" });
|
|
134
|
+
if (!response.ok) return fail(response);
|
|
135
|
+
return readInfo(root, response.headers, merged.size ?? DEFAULT_SIZE);
|
|
136
|
+
},
|
|
137
|
+
async list(collection = defaults.collection) {
|
|
138
|
+
const qs = collection ? `?collection=${encodeURIComponent(collection)}` : "";
|
|
139
|
+
const response = await doFetch(`${root}/photos${qs}`);
|
|
140
|
+
if (!response.ok) return fail(response);
|
|
141
|
+
return await response.json();
|
|
142
|
+
},
|
|
143
|
+
pick(seed, index) {
|
|
144
|
+
return pick(seed, Array.isArray(index) ? index : index.photos);
|
|
145
|
+
}
|
|
146
|
+
};
|
|
147
|
+
return client;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
// src/cli.ts
|
|
151
|
+
var HELP = `veyce \u2014 GTA VI character avatars from the veyce API
|
|
152
|
+
|
|
153
|
+
Usage
|
|
154
|
+
veyce url [options] print the avatar URL
|
|
155
|
+
veyce get [options] -o FILE download the avatar
|
|
156
|
+
veyce resolve [options] which image a seed/id lands on (JSON)
|
|
157
|
+
veyce list [--collection C] list every image id (JSON)
|
|
158
|
+
|
|
159
|
+
Options
|
|
160
|
+
--base URL service URL (or set VEYCE_URL; default https://veyce.vercel.app)
|
|
161
|
+
-s, --seed TEXT any string: email, username, uuid... always resolves
|
|
162
|
+
-i, --id ID exact image id (404 if unknown, unless --seed is also given)
|
|
163
|
+
-c, --collection C collection, e.g. gta-vi
|
|
164
|
+
--size N 8-2160 (default 80)
|
|
165
|
+
--crop NAME square | portrait | landscape | phone | tablet | ultrawide
|
|
166
|
+
--fit full keep original aspect ratio
|
|
167
|
+
--square square corners instead of a circle
|
|
168
|
+
--format F webp | png | jpeg
|
|
169
|
+
--bg HEX JPEG corner fill
|
|
170
|
+
-o, --out FILE output file for \`get\` (default: <id-or-seed>.<format>)
|
|
171
|
+
-h, --help
|
|
172
|
+
|
|
173
|
+
Examples
|
|
174
|
+
veyce url --seed ada@example.com --size 96
|
|
175
|
+
veyce get --seed ada@example.com -c gta-vi --size 256 -o ada.webp
|
|
176
|
+
`;
|
|
177
|
+
async function main() {
|
|
178
|
+
const { values, positionals } = parseArgs({
|
|
179
|
+
allowPositionals: true,
|
|
180
|
+
options: {
|
|
181
|
+
base: { type: "string" },
|
|
182
|
+
seed: { type: "string", short: "s" },
|
|
183
|
+
id: { type: "string", short: "i" },
|
|
184
|
+
collection: { type: "string", short: "c" },
|
|
185
|
+
size: { type: "string" },
|
|
186
|
+
crop: { type: "string" },
|
|
187
|
+
fit: { type: "string" },
|
|
188
|
+
square: { type: "boolean" },
|
|
189
|
+
format: { type: "string" },
|
|
190
|
+
bg: { type: "string" },
|
|
191
|
+
out: { type: "string", short: "o" },
|
|
192
|
+
help: { type: "boolean", short: "h" }
|
|
193
|
+
}
|
|
194
|
+
});
|
|
195
|
+
const command = positionals[0];
|
|
196
|
+
if (values.help || !command) {
|
|
197
|
+
process.stdout.write(HELP);
|
|
198
|
+
return command || values.help ? 0 : 1;
|
|
199
|
+
}
|
|
200
|
+
const baseUrl = values.base ?? process.env.VEYCE_URL ?? DEFAULT_BASE_URL;
|
|
201
|
+
if (values.format && !FORMATS.includes(values.format)) {
|
|
202
|
+
process.stderr.write(`veyce: --format must be one of ${FORMATS.join(", ")}.
|
|
203
|
+
`);
|
|
204
|
+
return 1;
|
|
205
|
+
}
|
|
206
|
+
if (values.fit && values.fit !== "full" && values.fit !== "cover") {
|
|
207
|
+
process.stderr.write("veyce: --fit must be cover or full.\n");
|
|
208
|
+
return 1;
|
|
209
|
+
}
|
|
210
|
+
const options = {
|
|
211
|
+
seed: values.seed,
|
|
212
|
+
id: values.id,
|
|
213
|
+
collection: values.collection,
|
|
214
|
+
size: values.size !== void 0 ? Number(values.size) : void 0,
|
|
215
|
+
crop: values.crop,
|
|
216
|
+
fit: values.fit,
|
|
217
|
+
square: values.square,
|
|
218
|
+
format: values.format,
|
|
219
|
+
background: values.bg
|
|
220
|
+
};
|
|
221
|
+
const avatars = createAvatars({ baseUrl });
|
|
222
|
+
switch (command) {
|
|
223
|
+
case "url":
|
|
224
|
+
process.stdout.write(`${avatars.url(options)}
|
|
225
|
+
`);
|
|
226
|
+
return 0;
|
|
227
|
+
case "resolve":
|
|
228
|
+
process.stdout.write(`${JSON.stringify(await avatars.resolve(options), null, 2)}
|
|
229
|
+
`);
|
|
230
|
+
return 0;
|
|
231
|
+
case "list":
|
|
232
|
+
process.stdout.write(`${JSON.stringify(await avatars.list(values.collection), null, 2)}
|
|
233
|
+
`);
|
|
234
|
+
return 0;
|
|
235
|
+
case "get": {
|
|
236
|
+
const image = await avatars.fetch(options);
|
|
237
|
+
const ext = image.contentType.split("/")[1] ?? "webp";
|
|
238
|
+
const name = (values.id ?? values.seed ?? image.info.id).replace(/[^\w.@-]+/g, "_");
|
|
239
|
+
const out = values.out ?? `${name}.${ext}`;
|
|
240
|
+
await writeFile(out, image.bytes);
|
|
241
|
+
process.stderr.write(
|
|
242
|
+
`saved ${out} (${image.info.collection}/${image.info.id}, ${image.info.size}px, matched by ${image.info.match})
|
|
243
|
+
`
|
|
244
|
+
);
|
|
245
|
+
return 0;
|
|
246
|
+
}
|
|
247
|
+
default:
|
|
248
|
+
process.stderr.write(`veyce: unknown command "${command}".
|
|
249
|
+
|
|
250
|
+
${HELP}`);
|
|
251
|
+
return 1;
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
main().then(
|
|
255
|
+
(code) => process.exit(code),
|
|
256
|
+
(error) => {
|
|
257
|
+
const message = error instanceof AvatarError || error instanceof Error ? error.message : String(error);
|
|
258
|
+
process.stderr.write(`${message}
|
|
259
|
+
`);
|
|
260
|
+
process.exit(1);
|
|
261
|
+
}
|
|
262
|
+
);
|