@bunizao/contracts 0.7.2 → 0.9.0

package/dist/comments.d.ts

@@ -60,6 +60,9 @@ export interface ReaderMe {
     provider: ReaderProvider;
     displayName: string;
     avatarUrl: string;
+    /** Seed of the drawn face shown when `avatarUrl` is empty. Null until one
+        has been handed out -- the client then draws from the name. */
+    avatarSeed: number | null;
     notifyReplies: boolean;
     /** Whether this address holds an active newsletter subscription. */
     subscribed: boolean;
@@ -101,9 +104,10 @@ export interface ReaderMuteResult {
     so this can never be used to probe which addresses have commented. */
 export interface ReaderResendInput {
     email: string;
-    /** Carries the original "notify me of replies" intent into the fresh
-        verification link, recovered from the stale token's payload. Optional;
-        a bare resend defaults to false. */
+    /** Newsletter opt-in, despite the name: carried into the fresh
+        verification link from the stale token's payload, and confirming the
+        address activates a newsletter subscription. Not the reply-mail switch
+        (that is `ReaderMe.notifyReplies`). Optional; a bare resend sends false. */
     notifyReplies?: boolean;
     locale?: CommentLocale;
 }
@@ -131,6 +135,8 @@ export declare const DEFAULT_REACTION_EMOJI = "\u2764\uFE0F";
 export interface ReactorChip {
     name: string;
     avatarUrl: string | null;
+    /** Drawn-face seed; absent from servers older than 0.8.0. */
+    avatarSeed?: number | null;
 }
 export interface ReactionSummary {
     emoji: string;
@@ -304,6 +310,10 @@ export interface CommentAuthor {
         any key it does not know, so a path emitted for every address would make
         every face an identicon. */
     avatarUrl: string;
+    /** Seed of the drawn face for an empty `avatarUrl`: the writer's reader
+        seed when they have one, else the seed the comment was posted with.
+        Null or absent (servers older than 0.8.0) means draw from the name. */
+    avatarSeed?: number | null;
     /** True when this row's writer is the blog owner. */
     byAuthor: boolean;
 }
@@ -361,14 +371,19 @@ export interface CommentCreateInput {
         Omitted or empty: the comment is owned by its anon session only and
         the client renders an identicon. */
     email?: string;
+    /** The drawn face the writer picked in the compose box, from
+        `READER_AVATAR_SEED_PATH`. Ignored when it is not an `isAvatarSeed`. */
+    avatarSeed?: number;
     turnstileToken: string;
     /** Visually-hidden honeypot field. Must arrive empty. */
     website?: string;
     /** Signed server timestamp minted at first interaction with the compose
         box — see "The risk stack" step 4 (dwell time). */
     dwellToken: string;
-    /** Reader accepted the post-comment subscribe offer. Only takes effect
-        once the address is verified. */
+    /** Newsletter opt-in, despite the name: the reader accepted the
+        post-comment subscribe offer, and confirming the address activates a
+        newsletter subscription. Not the reply-mail switch (that is
+        `ReaderMe.notifyReplies`). Both clients send false. */
     notifyReplies?: boolean;
     locale?: CommentLocale;
     /** Client evidence, optional and never a gate -- see `ClientEvidence`. */
@@ -426,47 +441,10 @@ export interface CommentPolicy {
     requireVerifiedEmail: boolean;
 }
 export declare const DEFAULT_COMMENT_POLICY: CommentPolicy;
-/** Ghost internal tags that override the site-wide default, one knob each.
- *
- * Internal tags are the switch because they are the only per-post field the
- * author already edits in Ghost, and both halves of the system can read them:
- * the site sees them through the Admin API at build time, site-api through the
- * Content API at request time (`include=tags` returns internal tags). One
- * source of truth, no settings table, no admin screen to keep in sync.
- *
- * `#no-comments` predates the others and is kept: it always meant "this post
- * takes no more comments", which is `readonly`. */
 export declare const COMMENT_POLICY_TAGS: {
-    readonly 'comments-off': (policy: CommentPolicy) => {
-        /** Whether the heart can be pressed — on the post and on its comments.
-            Independent of `mode`: a post can take reactions with comments off, and
-            an open thread can refuse them. */
-        reactions: boolean;
-        /** Accept a comment only from an address that has been verified. Anonymous
-            and unverified-email writers are refused rather than held. */
-        requireVerifiedEmail: boolean;
-        mode: CommentsMode;
-    };
-    readonly 'comments-readonly': (policy: CommentPolicy) => {
-        /** Whether the heart can be pressed — on the post and on its comments.
-            Independent of `mode`: a post can take reactions with comments off, and
-            an open thread can refuse them. */
-        reactions: boolean;
-        /** Accept a comment only from an address that has been verified. Anonymous
-            and unverified-email writers are refused rather than held. */
-        requireVerifiedEmail: boolean;
-        mode: CommentsMode;
-    };
-    readonly 'no-comments': (policy: CommentPolicy) => {
-        /** Whether the heart can be pressed — on the post and on its comments.
-            Independent of `mode`: a post can take reactions with comments off, and
-            an open thread can refuse them. */
-        reactions: boolean;
-        /** Accept a comment only from an address that has been verified. Anonymous
-            and unverified-email writers are refused rather than held. */
-        requireVerifiedEmail: boolean;
-        mode: CommentsMode;
-    };
+    readonly 'comments-off': (policy: CommentPolicy) => CommentPolicy;
+    readonly 'comments-readonly': (policy: CommentPolicy) => CommentPolicy;
+    readonly 'no-comments': (policy: CommentPolicy) => CommentPolicy;
     readonly 'reactions-off': (policy: CommentPolicy) => {
         mode: CommentsMode;
         /** Accept a comment only from an address that has been verified. Anonymous
@@ -490,7 +468,8 @@ export interface CommentPolicyTagLike {
     slug?: string | null;
 }
 /** Fold a post's tags onto the site-wide default. Order does not matter:
-    every tag sets one field, and a tag the map does not know is ignored. */
+    every tag sets one field, conflicting mode tags keep the stricter mode, and
+    a tag the map does not know is ignored. */
 export declare function commentPolicyFromTags(tags: readonly CommentPolicyTagLike[] | null | undefined, base?: CommentPolicy): CommentPolicy;
 /** Whether the post takes new comments — the one question the API asks. Both
     `readonly` and `off` answer no; the difference between them is drawn, not
@@ -523,3 +502,29 @@ export interface CommentTelemetryInput {
     outcome: 'accepted' | 'http_error' | 'network_error' | 'challenge_failed';
     challenges: number;
 }
+/** A drawn face's colour pair is `seed % AVATAR_CLASSES`: five palette
+    colours as background, times the four others as head. The pair is what
+    tells two faces apart at stack size, so it is the unit the server balances
+    when it hands out a seed and the unit a re-roll must change. The palette
+    itself is a rendering concern and lives with the client. */
+export declare const AVATAR_CLASSES = 20;
+export declare const MAX_AVATAR_SEED = 4294967295;
+export declare function isAvatarSeed(value: unknown): value is number;
+export declare function avatarClass(seed: number): number;
+/** A seed in colour class `cls`; `variety` fills the digits that pick the
+    expression, pose and head shape. */
+export declare function seedInClass(cls: number, variety: number): number;
+/** POST body for `READER_AVATAR_SEED_PATH`. */
+export interface AvatarSeedInput {
+    /** The seed on screen now. The answer is always in a different colour
+        class, so every re-roll visibly changes the face. */
+    current?: number | null;
+}
+export interface AvatarSeedResult {
+    /** In the least-used colour class across the site, never `current`'s. */
+    seed: number;
+    /** True when the caller is a verified reader and the seed is now theirs
+        everywhere. False for anyone else: the client keeps it and sends it as
+        `CommentCreateInput.avatarSeed`. */
+    persisted: boolean;
+}

package/dist/comments.js

@@ -32,10 +32,11 @@ var DEFAULT_COMMENT_POLICY = {
   reactions: true,
   requireVerifiedEmail: false
 };
+var withStricterMode = (policy, mode) => COMMENTS_MODES.indexOf(mode) > COMMENTS_MODES.indexOf(policy.mode) ? { ...policy, mode } : policy;
 var COMMENT_POLICY_TAGS = {
-  "comments-off": (policy) => ({ ...policy, mode: "off" }),
-  "comments-readonly": (policy) => ({ ...policy, mode: "readonly" }),
-  "no-comments": (policy) => ({ ...policy, mode: "readonly" }),
+  "comments-off": (policy) => withStricterMode(policy, "off"),
+  "comments-readonly": (policy) => withStricterMode(policy, "readonly"),
+  "no-comments": (policy) => withStricterMode(policy, "readonly"),
   "reactions-off": (policy) => ({ ...policy, reactions: false }),
   "comments-verified": (policy) => ({ ...policy, requireVerifiedEmail: true })
 };
@@ -61,7 +62,20 @@ function commentPolicyFromTags(tags, base = DEFAULT_COMMENT_POLICY) {
   return policy;
 }
 var acceptsComments = (policy) => policy.mode === "open";
+var AVATAR_CLASSES = 20;
+var MAX_AVATAR_SEED = 4294967295;
+function isAvatarSeed(value) {
+  return Number.isInteger(value) && value >= 0 && value <= MAX_AVATAR_SEED;
+}
+function avatarClass(seed) {
+  return seed % AVATAR_CLASSES;
+}
+function seedInClass(cls, variety) {
+  const span = Math.floor(MAX_AVATAR_SEED / AVATAR_CLASSES);
+  return Math.abs(Math.trunc(variety)) % span * AVATAR_CLASSES + Math.abs(Math.trunc(cls)) % AVATAR_CLASSES;
+}
 export {
+  AVATAR_CLASSES,
   COMMENTS_MODES,
   COMMENT_ANCHOR_PATTERN,
   COMMENT_ANCHOR_TOKEN_LENGTH,
@@ -72,6 +86,7 @@ export {
   COMMENT_SURFACES,
   DEFAULT_COMMENT_POLICY,
   DEFAULT_REACTION_EMOJI,
+  MAX_AVATAR_SEED,
   MODERATION_ACTIONS,
   MODERATION_REASONS,
   REACTION_TARGET_TYPES,
@@ -80,6 +95,9 @@ export {
   READER_PROVIDERS,
   READER_VERIFY_OUTCOMES,
   acceptsComments,
+  avatarClass,
   commentAnchorToken,
-  commentPolicyFromTags
+  commentPolicyFromTags,
+  isAvatarSeed,
+  seedInClass
 };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './analytics';
 export * from './admin';
 export * from './comments';
 export * from './content';
+export * from './instagram';
 export * from './listening';
 export * from './messages';
 export * from './mood';

package/dist/index.js

@@ -44,10 +44,11 @@ var DEFAULT_COMMENT_POLICY = {
   reactions: true,
   requireVerifiedEmail: false
 };
+var withStricterMode = (policy, mode) => COMMENTS_MODES.indexOf(mode) > COMMENTS_MODES.indexOf(policy.mode) ? { ...policy, mode } : policy;
 var COMMENT_POLICY_TAGS = {
-  "comments-off": (policy) => ({ ...policy, mode: "off" }),
-  "comments-readonly": (policy) => ({ ...policy, mode: "readonly" }),
-  "no-comments": (policy) => ({ ...policy, mode: "readonly" }),
+  "comments-off": (policy) => withStricterMode(policy, "off"),
+  "comments-readonly": (policy) => withStricterMode(policy, "readonly"),
+  "no-comments": (policy) => withStricterMode(policy, "readonly"),
   "reactions-off": (policy) => ({ ...policy, reactions: false }),
   "comments-verified": (policy) => ({ ...policy, requireVerifiedEmail: true })
 };
@@ -73,6 +74,18 @@ function commentPolicyFromTags(tags, base = DEFAULT_COMMENT_POLICY) {
   return policy;
 }
 var acceptsComments = (policy) => policy.mode === "open";
+var AVATAR_CLASSES = 20;
+var MAX_AVATAR_SEED = 4294967295;
+function isAvatarSeed(value) {
+  return Number.isInteger(value) && value >= 0 && value <= MAX_AVATAR_SEED;
+}
+function avatarClass(seed) {
+  return seed % AVATAR_CLASSES;
+}
+function seedInClass(cls, variety) {
+  const span = Math.floor(MAX_AVATAR_SEED / AVATAR_CLASSES);
+  return Math.abs(Math.trunc(variety)) % span * AVATAR_CLASSES + Math.abs(Math.trunc(cls)) % AVATAR_CLASSES;
+}
 // src/content.ts
 var CONTENT_DOCUMENT_SOURCES = ["mood", "post"];
 var POST_LOCALE_RE = /^[a-z]{2,8}(?:-[a-z0-9]{1,8})*$/;
@@ -119,6 +132,8 @@ var MOOD_SEARCH_PATH = "/v2/mood/search";
 var MOOD_IMAGE_PROXY_BASE_PATH = "/v2/images";
 var MOOD_MEDIA_PROXY_BASE_PATH = "/v2/media";
 var LISTENING_PATH = "/v2/listening";
+var INSTAGRAM_PROFILE_PATH = "/v2/instagram";
+var INSTAGRAM_AVATAR_PATH = "/v2/instagram/avatar";
 var COMMENTS_PATH = "/v2/comments";
 var COMMENT_PATH_PREFIX = "/v2/comments/";
 var OWNER_MESSAGES_PATH = "/v2/messages";
@@ -130,6 +145,7 @@ var READER_RESEND_PATH = "/v2/reader/resend";
 var READER_PREFERENCES_PATH = "/v2/reader/preferences";
 var READER_MUTE_PATH = "/v2/reader/mute";
 var READER_AVATAR_PATH_PREFIX = "/v2/reader/avatar/";
+var READER_AVATAR_SEED_PATH = "/v2/reader/avatar-seed";
 var READER_OAUTH_PATH_PREFIX = "/oauth/reader/";
 var READER_CONFIRM_PATH = "/reader/confirm";
 var READER_MUTE_PAGE_PATH = "/reader/mute";
@@ -203,6 +219,7 @@ var TELEGRAM_OPS_BROADCAST_STATUSES = [
 export {
   ADMIN_BASE_PATH,
   API_PREFIX,
+  AVATAR_CLASSES,
   BLOG_ANALYTICS_ARTICLE_ENDPOINT,
   BLOG_ANALYTICS_COMPLETION_SCROLL_DEPTH,
   BLOG_ANALYTICS_EVENTS_DEFAULT_LIMIT,
@@ -227,6 +244,8 @@ export {
   EVENT_STATUSES,
   GHOST_WEBHOOK_PATH,
   HEALTH_PATH,
+  INSTAGRAM_AVATAR_PATH,
+  INSTAGRAM_PROFILE_PATH,
   LEGACY_ADMIN_BASE_PATH,
   LEGACY_GHOST_WEBHOOK_PATH,
   LEGACY_HEALTH_PATH,
@@ -234,6 +253,7 @@ export {
   LEGACY_NOTIFY_BASE_PATH,
   LISTENING_ANALYTICS_EVENT_ENDPOINT,
   LISTENING_PATH,
+  MAX_AVATAR_SEED,
   MESSAGE_LOCALES,
   MESSAGE_MAX_BODY_LENGTH,
   MESSAGE_MAX_NAME_LENGTH,
@@ -269,6 +289,7 @@ export {
   REACTIONS_TOGGLE_PATH,
   REACTION_TARGET_TYPES,
   READER_AVATAR_PATH_PREFIX,
+  READER_AVATAR_SEED_PATH,
   READER_CONFIRM_PATH,
   READER_GRADES,
   READER_ME_PATH,
@@ -298,9 +319,12 @@ export {
   TELEGRAM_OPS_WEBHOOK_PATH,
   TELEGRAM_WEBHOOK_PATH,
   acceptsComments,
+  avatarClass,
   commentAnchorToken,
   commentPolicyFromTags,
+  isAvatarSeed,
   parsePostLocaleTag,
+  seedInClass,
   telegramOpsEventActionPath,
   telegramOpsEventPath,
   telegramOpsReminderDeliveredPath,

package/dist/instagram.d.ts

@@ -0,0 +1,29 @@
+export interface InstagramProfileCounts {
+    posts: number;
+    followers: number;
+    following: number;
+}
+export interface InstagramProfileAvatar {
+    /** Absolute URL of the stored picture, served by site-api. */
+    url: string;
+    contentType: string;
+    bytes: number;
+    /** Hex SHA-256 of the stored bytes; the avatar route sends it as the ETag. */
+    sha256: string;
+}
+export interface InstagramProfileAttempt {
+    at: string;
+    ok: boolean;
+    /** Why the attempt failed, e.g. `profile:401`; null when it succeeded. */
+    error: string | null;
+}
+export interface InstagramProfile {
+    username: string;
+    fullName: string;
+    profileUrl: string;
+    avatar: InstagramProfileAvatar;
+    counts: InstagramProfileCounts;
+    /** When the stored profile was last read from Instagram. */
+    refreshedAt: string;
+    lastAttempt: InstagramProfileAttempt;
+}

package/dist/routes.d.ts

@@ -12,6 +12,8 @@ export declare const MOOD_SEARCH_PATH: '/v2/mood/search';
 export declare const MOOD_IMAGE_PROXY_BASE_PATH: '/v2/images';
 export declare const MOOD_MEDIA_PROXY_BASE_PATH: '/v2/media';
 export declare const LISTENING_PATH: '/v2/listening';
+export declare const INSTAGRAM_PROFILE_PATH: '/v2/instagram';
+export declare const INSTAGRAM_AVATAR_PATH: '/v2/instagram/avatar';
 export declare const COMMENTS_PATH: '/v2/comments';
 export declare const COMMENT_PATH_PREFIX: '/v2/comments/';
 export declare const OWNER_MESSAGES_PATH: '/v2/messages';
@@ -23,6 +25,7 @@ export declare const READER_RESEND_PATH: '/v2/reader/resend';
 export declare const READER_PREFERENCES_PATH: '/v2/reader/preferences';
 export declare const READER_MUTE_PATH: '/v2/reader/mute';
 export declare const READER_AVATAR_PATH_PREFIX: '/v2/reader/avatar/';
+export declare const READER_AVATAR_SEED_PATH: '/v2/reader/avatar-seed';
 export declare const READER_OAUTH_PATH_PREFIX: '/oauth/reader/';
 export declare const READER_CONFIRM_PATH: '/reader/confirm';
 export declare const READER_MUTE_PAGE_PATH: '/reader/mute';

package/dist/routes.js

@@ -13,6 +13,8 @@ var MOOD_SEARCH_PATH = "/v2/mood/search";
 var MOOD_IMAGE_PROXY_BASE_PATH = "/v2/images";
 var MOOD_MEDIA_PROXY_BASE_PATH = "/v2/media";
 var LISTENING_PATH = "/v2/listening";
+var INSTAGRAM_PROFILE_PATH = "/v2/instagram";
+var INSTAGRAM_AVATAR_PATH = "/v2/instagram/avatar";
 var COMMENTS_PATH = "/v2/comments";
 var COMMENT_PATH_PREFIX = "/v2/comments/";
 var OWNER_MESSAGES_PATH = "/v2/messages";
@@ -24,6 +26,7 @@ var READER_RESEND_PATH = "/v2/reader/resend";
 var READER_PREFERENCES_PATH = "/v2/reader/preferences";
 var READER_MUTE_PATH = "/v2/reader/mute";
 var READER_AVATAR_PATH_PREFIX = "/v2/reader/avatar/";
+var READER_AVATAR_SEED_PATH = "/v2/reader/avatar-seed";
 var READER_OAUTH_PATH_PREFIX = "/oauth/reader/";
 var READER_CONFIRM_PATH = "/reader/confirm";
 var READER_MUTE_PAGE_PATH = "/reader/mute";
@@ -44,6 +47,8 @@ export {
   COMMENT_PATH_PREFIX,
   GHOST_WEBHOOK_PATH,
   HEALTH_PATH,
+  INSTAGRAM_AVATAR_PATH,
+  INSTAGRAM_PROFILE_PATH,
   LEGACY_ADMIN_BASE_PATH,
   LEGACY_GHOST_WEBHOOK_PATH,
   LEGACY_HEALTH_PATH,
@@ -67,6 +72,7 @@ export {
   REACTIONS_PATH,
   REACTIONS_TOGGLE_PATH,
   READER_AVATAR_PATH_PREFIX,
+  READER_AVATAR_SEED_PATH,
   READER_CONFIRM_PATH,
   READER_ME_PATH,
   READER_MUTE_PAGE_PATH,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunizao/contracts",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "Shared TypeScript contracts for buxx.me services and clients.",
   "type": "module",
   "sideEffects": false,
@@ -48,6 +48,11 @@
       "import": "./dist/content.js",
       "default": "./dist/content.js"
     },
+    "./instagram": {
+      "types": "./dist/instagram.d.ts",
+      "import": "./dist/instagram.js",
+      "default": "./dist/instagram.js"
+    },
     "./listening": {
       "types": "./dist/listening.d.ts",
       "import": "./dist/listening.js",