Provider seam for the Avatar Protocol.
The Avatar Protocol (game.protocols.avatar) is provider-agnostic: it owns the
game-state and the event contract, but never talks to an avatar service
directly. Every outbound call goes through this AvatarProvider seam, and the
GM-side interceptor (game.handlers) resolves the configured implementation and
runs it (holding the service credentials — the withdrawal/Stripe "key locality"
pattern). Yvatar is the first implementation
(game.protocols.providers.yvatar); adding another provider later means a new
defrecord + a factory case, and nothing in the protocol layer changes.
Every method takes a provider-neutral ctx:
{:provider <string> ; e.g. the game-name — maps to Yvatar external_provider
:external-user-id <string>} ; e.g. the player-name — maps to Yvatar external_user_id
Every method returns ONE of:
{:ok? true :avatar {:avatar-id :public-handle :portrait-url
:pending-portrait-url :public-url :name :status
;; draft-post / regenerate-post / fetch-post-status
;; also return:
:post-id :post-status :prompt :caption :preview-url
;; confirm-publish also returns:
:platform :post-url :platform-post-id ...}}
{:ok? false :status <int|keyword> :error <any>}
The :avatar map is already provider-neutral (kebab-case keys); the protocol
layer and interceptor only ever see this shape, never provider-specific JSON.
Provider seam for the Avatar Protocol.
The Avatar Protocol (`game.protocols.avatar`) is provider-agnostic: it owns the
game-state and the event contract, but never talks to an avatar service
directly. Every outbound call goes through this `AvatarProvider` seam, and the
GM-side interceptor (`game.handlers`) resolves the configured implementation and
runs it (holding the service credentials — the withdrawal/Stripe "key locality"
pattern). Yvatar is the first implementation
(`game.protocols.providers.yvatar`); adding another provider later means a new
`defrecord` + a factory case, and nothing in the protocol layer changes.
## Context map
Every method takes a provider-neutral `ctx`:
{:provider <string> ; e.g. the game-name — maps to Yvatar external_provider
:external-user-id <string>} ; e.g. the player-name — maps to Yvatar external_user_id
## Normalized result
Every method returns ONE of:
{:ok? true :avatar {:avatar-id :public-handle :portrait-url
:pending-portrait-url :public-url :name :status
;; draft-post / regenerate-post / fetch-post-status
;; also return:
:post-id :post-status :prompt :caption :preview-url
;; confirm-publish also returns:
:platform :post-url :platform-post-id ...}}
{:ok? false :status <int|keyword> :error <any>}
The `:avatar` map is already provider-neutral (kebab-case keys); the protocol
layer and interceptor only ever see this shape, never provider-specific JSON.Provider-neutral avatar operations. Implementations translate to/from their own API here and MUST return the normalized result documented in the ns docstring.
Provider-neutral avatar operations. Implementations translate to/from their own API here and MUST return the normalized result documented in the ns docstring.
(confirm-publish this ctx platform)Publish the mapped avatar's current draft post live to platform (a
neutral platform keyword/string, e.g. "youtube", "twitter"). Requires
the pending post to have finished generating (see fetch-post-status).
Publish the mapped avatar's current draft post live to `platform` (a neutral platform keyword/string, e.g. "youtube", "twitter"). Requires the pending post to have finished generating (see fetch-post-status).
(upsert-persona this ctx persona)Create or update the mapped avatar's persona. persona is a map of neutral
(kebab-case keyword) persona fields.
Create or update the mapped avatar's persona. `persona` is a map of neutral (kebab-case keyword) persona fields.
(fetch-persona this ctx)Fetch the full rich persona for the mapped avatar.
Fetch the full rich persona for the mapped avatar.
(accept-portrait this ctx)Promote the pending portrait to the accepted portrait for the mapped avatar.
Promote the pending portrait to the accepted portrait for the mapped avatar.
(fetch-public this ctx)Fetch the embed-safe public profile shape for the mapped avatar.
Fetch the embed-safe public profile shape for the mapped avatar.
(draft-post this ctx post)Draft a new video post for the mapped avatar, pending review. post is
{:prompt <string>} (the script). Video generation is asynchronous — this
returns immediately with a :post-status of "generating_video"; use
fetch-post-status to check on it. Replaces any prior draft.
Draft a new video post for the mapped avatar, pending review. `post` is
{:prompt <string>} (the script). Video generation is asynchronous — this
returns immediately with a :post-status of "generating_video"; use
fetch-post-status to check on it. Replaces any prior draft.(generate-portrait this ctx)Generate a pending portrait for the mapped avatar (may consume a credit).
Generate a pending portrait for the mapped avatar (may consume a credit).
(fetch-post-status this ctx)Check the mapped avatar's current pending post on demand — a single synchronous check, NOT a polling loop. Video generation is async, so a caller (e.g. a player-facing "refresh" action) uses this to learn whether a prior draft-post/regenerate-post call has finished.
Check the mapped avatar's current pending post on demand — a single synchronous check, NOT a polling loop. Video generation is async, so a caller (e.g. a player-facing "refresh" action) uses this to learn whether a prior draft-post/regenerate-post call has finished.
(regenerate-post this ctx feedback)Redraft the mapped avatar's current pending post, optionally guided by
feedback (a string, may be nil). Video posts only. Also asynchronous —
returns immediately, check via fetch-post-status.
Redraft the mapped avatar's current pending post, optionally guided by `feedback` (a string, may be nil). Video posts only. Also asynchronous — returns immediately, check via fetch-post-status.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |