@bunizao/contracts 0.28.0 → 0.29.0

package/dist/index.d.ts

@@ -10,3 +10,4 @@ export * from './mood';
 export * from './notify';
 export * from './routes';
 export * from './telegram-ops';
+export * from './year';

package/dist/index.js

@@ -223,6 +223,7 @@ var MOOD_ARCHIVE_FEED_PATH = "/v2/mood";
 var MOOD_LIVE_COUNTS_PATH = "/v2/moods/live-counts";
 var MOOD_ARCHIVE_STATS_PATH = "/v2/mood/stats";
 var MOOD_SEARCH_PATH = "/v2/mood/search";
+var YEAR_REVIEW_PATH = "/v2/year";
 var MOOD_ON_THIS_DAY_PATH = "/v2/mood/on-this-day";
 var MOOD_DAYS_PATH = "/v2/mood/days";
 var MOOD_DATE_PATH = "/v2/mood/date";
@@ -455,6 +456,7 @@ export {
   TELEGRAM_OPS_SUBSCRIBER_STATUSES,
   TELEGRAM_OPS_WEBHOOK_PATH,
   TELEGRAM_WEBHOOK_PATH,
+  YEAR_REVIEW_PATH,
   acceptsComments,
   avatarClass,
   commentAnchorToken,

package/dist/routes.d.ts

@@ -9,6 +9,7 @@ export declare const MOOD_ARCHIVE_FEED_PATH: '/v2/mood';
 export declare const MOOD_LIVE_COUNTS_PATH: '/v2/moods/live-counts';
 export declare const MOOD_ARCHIVE_STATS_PATH: '/v2/mood/stats';
 export declare const MOOD_SEARCH_PATH: '/v2/mood/search';
+export declare const YEAR_REVIEW_PATH: '/v2/year';
 export declare const MOOD_ON_THIS_DAY_PATH: '/v2/mood/on-this-day';
 export declare const MOOD_DAYS_PATH: '/v2/mood/days';
 export declare const MOOD_DATE_PATH: '/v2/mood/date';

package/dist/routes.js

@@ -10,6 +10,7 @@ var MOOD_ARCHIVE_FEED_PATH = "/v2/mood";
 var MOOD_LIVE_COUNTS_PATH = "/v2/moods/live-counts";
 var MOOD_ARCHIVE_STATS_PATH = "/v2/mood/stats";
 var MOOD_SEARCH_PATH = "/v2/mood/search";
+var YEAR_REVIEW_PATH = "/v2/year";
 var MOOD_ON_THIS_DAY_PATH = "/v2/mood/on-this-day";
 var MOOD_DAYS_PATH = "/v2/mood/days";
 var MOOD_DATE_PATH = "/v2/mood/date";
@@ -99,5 +100,6 @@ export {
   READER_RESEND_PATH,
   READER_VERIFY_PATH,
   TELEGRAM_WEBHOOK_PATH,
+  YEAR_REVIEW_PATH,
   deskIconPath
 };

package/dist/year.d.ts

@@ -0,0 +1,169 @@
+import type { MoodYear } from './mood';
+/** A ranked artist in the year's listening. */
+export interface YearListeningArtist {
+    name: string;
+    plays: number;
+    /** The artist's Last.fm page. */
+    url: string;
+}
+/** A ranked track in the year's listening. */
+export interface YearListeningTrack {
+    title: string;
+    artist: string;
+    plays: number;
+    /** The track's Last.fm page. */
+    url: string;
+}
+/** A ranked album in the year's listening. */
+export interface YearListeningAlbum {
+    title: string;
+    artist: string;
+    plays: number;
+    /** The album's Last.fm page. */
+    url: string;
+    /** Last.fm's square cover, about 300px; null when it has none. */
+    image: string | null;
+}
+/** One calendar month of the year's listening. */
+export interface YearListeningMonth {
+    /** 1-12. */
+    month: number;
+    plays: number;
+    /** The month's most played track; null when Last.fm would not chart the
+        month's own range or nothing was played. */
+    track: YearListeningTrack | null;
+}
+/** The owner's Last.fm scrobbles in the calendar year, up to the snapshot. */
+export interface YearListening {
+    plays: number;
+    /** At most ten, most played first. Empty when Last.fm would not chart the
+        year's own range: a list for some other span is never shown as this one. */
+    artists: YearListeningArtist[];
+    /** At most ten, most played first; empty on the same terms. */
+    tracks: YearListeningTrack[];
+    /** At most six, most played first; empty on the same terms. */
+    albums: YearListeningAlbum[];
+    /** Every month the snapshot has reached, January first. */
+    months: YearListeningMonth[];
+}
+export interface YearGitHubDay {
+    /** YYYY-MM-DD. */
+    date: string;
+    count: number;
+    /** GitHub's own quartile, 0 (none) to 4. */
+    level: number;
+}
+/** The year's contributions by kind, as GitHub counts them. */
+export interface YearGitHubKinds {
+    commits: number;
+    pullRequests: number;
+    reviews: number;
+    issues: number;
+    /** Repositories with at least one of the owner's commits. */
+    repositories: number;
+}
+/** A public repository the owner worked in or created during the year. */
+export interface YearGitHubRepository {
+    /** owner/name. */
+    name: string;
+    url: string;
+    description: string | null;
+    /** The primary language's name; null when GitHub has none. */
+    language: string | null;
+    stars: number;
+    /** The owner's commits to it in the year; 0 for a repository only created. */
+    commits: number;
+    /** When it was created, ISO 8601. */
+    createdAt: string;
+}
+/** The owner's public GitHub contributions in the calendar year. */
+export interface YearGitHub {
+    total: number;
+    /** Every day of the year up to the snapshot, ascending. */
+    days: YearGitHubDay[];
+    /** Null when the snapshot was built without a GitHub token: the public
+        calendar mirror has no breakdown. */
+    kinds: YearGitHubKinds | null;
+    /** Public repositories by the owner's commits in the year, at most eight.
+        Private ones are never listed. */
+    repositories: YearGitHubRepository[];
+    /** Public repositories the owner created in the year, oldest first, at
+        most eight. */
+    created: YearGitHubRepository[];
+}
+/** One of the owner's own moods, as the review quotes it. */
+export interface YearMoodMoment {
+    /** The mood's message id: /mood/<id>. */
+    id: number;
+    /** When it was posted, ISO 8601. */
+    at: string;
+    /** The opening of its text, plain, at most 160 characters; empty for a
+        photo without a caption. */
+    text: string;
+    /** Reactions when the review was generated. */
+    reactions: number;
+    comments: number;
+    /** Whether it carries a photo, served at /api/v2/images/mood/<id>/0. */
+    photo: boolean;
+}
+/** The year's own moods beyond the daily tallies in `mood`. Forwards are
+    left out, as there. */
+export interface YearMoments {
+    /** Each own mood's minute of the year on the owner's Melbourne wall clock
+        (day of the year from 0, times 1440, plus the minute of that day),
+        ascending. */
+    minutes: number[];
+    /** The year's first and last own moods. */
+    first: YearMoodMoment | null;
+    last: YearMoodMoment | null;
+    /** The moods readers answered most (reactions plus comments), at most six,
+        most first. Only moods with at least one reaction or comment. */
+    loved: YearMoodMoment[];
+    /** At most one photo a month, the one readers answered most, January
+        first. */
+    photos: YearMoodMoment[];
+}
+/** Lifetime blog reads when the snapshot was built, only for a year the
+    counter was already running in. Never per post: those stay in the owner's
+    portal. */
+export interface YearBlogReads {
+    reads: number;
+    /** When counting began, ISO 8601; null when the start is not known. */
+    since: string | null;
+}
+/** One calendar year across the site, generated when the owner asks for it
+    and kept until they ask again. A year generated before it ended on the
+    owner's Melbourne clock is the year so far, up to `through`. Each part is
+    null when that year has nothing from its source. */
+export interface YearReview {
+    year: number;
+    /** The last Melbourne day the snapshot covers, YYYY-MM-DD. */
+    through: string;
+    mood: MoodYear | null;
+    /** Null when the year has no own moods. */
+    moments: YearMoments | null;
+    listening: YearListening | null;
+    github: YearGitHub | null;
+    blog: YearBlogReads | null;
+    generatedAt: string;
+}
+/** `GET /v2/year` without a year: every year that has a review, newest
+    first. */
+export interface YearReviewIndex {
+    years: {
+        year: number;
+        generatedAt: string;
+    }[];
+}
+/** One year as the owner's generate list shows it. */
+export interface YearReviewState {
+    year: number;
+    /** When the published review was generated; null when there is none. */
+    generatedAt: string | null;
+    /** The last attempt, when it failed after the published review (or with
+        none published). The published review, if any, stays up. */
+    failure: {
+        at: string;
+        reason: string;
+    } | null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunizao/contracts",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Shared TypeScript contracts for buxx.me services and clients.",
   "type": "module",
   "sideEffects": false,
@@ -92,6 +92,11 @@
       "types": "./dist/telegram-ops.d.ts",
       "import": "./dist/telegram-ops.js",
       "default": "./dist/telegram-ops.js"
+    },
+    "./year": {
+      "types": "./dist/year.d.ts",
+      "import": "./dist/year.js",
+      "default": "./dist/year.js"
     }
   },
   "files": [