@bunizao/contracts 0.8.0 → 0.10.0

package/dist/comments.d.ts

@@ -104,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;
 }
@@ -379,8 +380,10 @@ export interface CommentCreateInput {
     /** 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`. */
@@ -438,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
@@ -502,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
@@ -547,17 +514,36 @@ 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`. */
+/** How many faces an `offer` holds. */
+export declare const AVATAR_OFFER_SIZE = 5;
+/** POST body for `READER_AVATAR_SEED_PATH`.
+
+    - `issue` (the default): one seed, handed out and counted. The first face
+      a browser gets.
+    - `offer`: AVATAR_OFFER_SIZE candidates to choose from, nothing counted
+      or kept -- a reader browsing faces has not taken one yet.
+    - `choose`: `seed` becomes the caller's face, counted and, for a verified
+      reader, kept. */
 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. */
+    /** The seed on screen now. `issue` and `offer` always answer in other
+        colour classes, so every new face visibly changes. */
     current?: number | null;
+    mode?: 'issue' | 'offer' | 'choose';
+    /** Required for `choose`. */
+    seed?: number;
 }
+/** The answer to `issue` and `choose`. */
 export interface AvatarSeedResult {
-    /** In the least-used colour class across the site, never `current`'s. */
+    /** For `issue`, in the least-used colour class across the site, never
+        `current`'s. For `choose`, the seed that was sent. */
     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;
 }
+/** The answer to `offer`: one seed in each of the AVATAR_OFFER_SIZE
+    least-used colour classes, none of them `current`'s. */
+export interface AvatarSeedOfferResult {
+    seeds: number[];
+}

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 })
 };
@@ -73,8 +74,10 @@ 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;
 }
+var AVATAR_OFFER_SIZE = 5;
 export {
   AVATAR_CLASSES,
+  AVATAR_OFFER_SIZE,
   COMMENTS_MODES,
   COMMENT_ANCHOR_PATTERN,
   COMMENT_ANCHOR_TOKEN_LENGTH,

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 })
 };
@@ -85,6 +86,7 @@ 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;
 }
+var AVATAR_OFFER_SIZE = 5;
 // src/content.ts
 var CONTENT_DOCUMENT_SOURCES = ["mood", "post"];
 var POST_LOCALE_RE = /^[a-z]{2,8}(?:-[a-z0-9]{1,8})*$/;
@@ -131,6 +133,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";
@@ -217,6 +221,7 @@ export {
   ADMIN_BASE_PATH,
   API_PREFIX,
   AVATAR_CLASSES,
+  AVATAR_OFFER_SIZE,
   BLOG_ANALYTICS_ARTICLE_ENDPOINT,
   BLOG_ANALYTICS_COMPLETION_SCROLL_DEPTH,
   BLOG_ANALYTICS_EVENTS_DEFAULT_LIMIT,
@@ -241,6 +246,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,

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';

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";
@@ -45,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunizao/contracts",
-  "version": "0.8.0",
+  "version": "0.10.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",