@stats-forge/github-stats-forge-core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Anurag Hazra, Abhijit Gupta, martin-mfg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @stats-forge/github-stats-forge-core
+
+Core library powering [GitHub Stats Forge](https://github.com/stats-forge/github-stats-forge):
+it turns GitHub and WakaTime data into SVG cards.
+
+It is what the CLI and any self-hosted endpoint call. Nothing here touches the
+environment or the filesystem — you pass a config in, you get a string of SVG back — so it
+behaves the same under Node, in a browser and under a test runner.
+
+```sh
+pnpm add @stats-forge/github-stats-forge-core
+```
+
+Requires Node 24 or newer.
+
+## Quick start
+
+An endpoint is one call. The handler parses the query string, fetches, renders, and hands
+back either the card or a rendered error:
+
+```ts
+import { CardConfig, stats } from '@stats-forge/github-stats-forge-core/api';
+
+const config = new CardConfig({ pats: [{ name: 'PAT_1', value: process.env.PAT_1! }] });
+
+const result = await stats({ username: 'anuraghazra', theme: 'tokyonight' }, config);
+
+if (result.status === 'error') {
+  console.error(result.error.code, result.error.message);
+}
+// `content` is an SVG either way: a failure is a card that says what went wrong.
+response.setHeader('Content-Type', 'image/svg+xml');
+response.end(result.content);
+```
+
+## Entry points
+
+Import the layer you need rather than the whole package:
+
+| Path        | What it holds                                              |
+| ----------- | ---------------------------------------------------------- |
+| `/api`      | The five endpoint handlers, `ApiResult`, `CardConfig`      |
+| `/cards`    | The render functions, for data you already hold            |
+| `/fetchers` | The GitHub and WakaTime fetchers, `retryer`, `CardError`   |
+| `/themes`   | The theme table and `ThemeName`                            |
+| `.`         | The handlers plus `CardConfig`, `themes` and `renderError` |
+
+## The five cards
+
+Each handler is a named export carrying the values its enum params accept, so a UI can
+read the choices off the function it calls instead of hardcoding them:
+
+| Handler    | Card                                     | Lists it carries             |
+| ---------- | ---------------------------------------- | ---------------------------- |
+| `stats`    | Commits, PRs, issues, reviews and a rank | `RANK_ICONS`                 |
+| `topLangs` | Most used languages                      | `LAYOUTS`, `STATS_FORMATS`   |
+| `pin`      | A pinned repository                      | —                            |
+| `gist`     | A gist                                   | —                            |
+| `wakatime` | WakaTime coding time                     | `LAYOUTS`, `DISPLAY_FORMATS` |
+
+```ts
+import { topLangs } from '@stats-forge/github-stats-forge-core/api';
+
+topLangs.LAYOUTS; // ['compact', 'normal', 'donut', 'donut-vertical', 'pie'] — what `?layout=` accepts
+```
+
+## Config
+
+`CardConfig` is built by the host rather than read from the environment, and it is
+immutable — `with()` returns a copy, which is how a host swaps in a per-request token:
+
+```ts
+import { CardConfig } from '@stats-forge/github-stats-forge-core/api';
+
+const base = CardConfig.fromEnv(process.env); // reads PAT_1, PAT_2, … plus the allowlists
+const forThisRequest = base.with({ pats: [{ name: 'user', value: userToken }] });
+```
+
+| Field                 | What it does                                                        |
+| --------------------- | ------------------------------------------------------------------- |
+| `pats`                | The token pool; the retryer rotates through it on a rate limit      |
+| `fetch`               | The transport every request goes through (see below)                |
+| `usernameAllowlist`   | Restrict which users this deployment serves; `undefined` allows all |
+| `gistAllowlist`       | The same, for gist ids                                              |
+| `excludeRepositories` | Repositories left out of star counts                                |
+| `fetchMultiPageStars` | How many pages of starred repos to walk; `Infinity` for all         |
+
+### Substituting the transport
+
+`fetch` defaults to the global one, resolved at call time. Passing your own is how you
+mock, cache or proxy every request the library makes — no global patching:
+
+```ts
+const config = new CardConfig({
+  pats,
+  fetch: async (url, init) => {
+    const cached = await cache.get(url);
+    return cached ?? cache.put(url, await fetch(url, init));
+  },
+});
+```
+
+## Rendering from data you already hold
+
+If you cache stats yourself, skip the fetchers and render directly:
+
+```ts
+import { renderStatsCard } from '@stats-forge/github-stats-forge-core/cards';
+
+const svg = renderStatsCard(myStats, { theme: 'dracula', hide_rank: true });
+```
+
+Every card is labelled for screen readers: the SVG carries `role="img"` with a `<title>`
+and `<desc>` describing what it shows, since assistive technology cannot reach the text
+inside an image role.
+
+## Errors
+
+Everything throws a `CardError`, and the handler turns it into a result rather than a
+rejection. `ApiResult` is a union, so a host branches on the code instead of parsing the
+SVG:
+
+```ts
+const result = await stats({ username }, config);
+if (result.status === 'error') {
+  const { code, param, message } = result.error;
+  // 'invalid_param' | 'missing_param' | 'not_found' | 'no_tokens' | 'rate_limited' | 'upstream'
+  if (result.retryable) {
+    // a retry may help; the rest are permanent and safe to cache
+  }
+}
+```
+
+## Themes
+
+```ts
+import { themes } from '@stats-forge/github-stats-forge-core/themes';
+
+Object.keys(themes); // 79 names, and what `?theme=` accepts
+```
+
+An unknown theme name falls back to the default rather than failing, so a typo still
+renders a card.
+
+## Acknowledgements
+
+It continues the work of [github-stats-extended](https://github.com/stats-organization/github-stats-extended),
+which is itself based on [github-readme-stats](https://github.com/anuraghazra/github-readme-stats).

package/build/api/api-result.d.ts

@@ -0,0 +1,44 @@
+import type { ColorParams } from '../common/color.js';
+import type { ErrorCode } from '../common/error.js';
+/**
+ * Why a card could not be rendered, in a form a host can act on.
+ * The same failure is also drawn onto the result's `content`,
+ * so a host never has to read the SVG to find out what happened.
+ */
+export interface ApiError {
+    /** Why it failed. */
+    code: ErrorCode;
+    /** First line of the error card. */
+    message: string;
+    /** Second line of the error card, when the code has more to say. */
+    secondaryMessage: string | undefined;
+    /**
+     * The first param at fault, when the failure names one.
+     * `missing_param` names every missing param in `message`, and not every
+     * `invalid_param` comes from a single param, so this can be absent.
+     */
+    param: string | undefined;
+}
+/** What every api handler returns: a rendered card, or a rendered error. */
+export type ApiResult = {
+    status: 'success';
+    content: string;
+} | {
+    status: 'error';
+    /** Whether repeating the request could produce a different answer. */
+    retryable: boolean;
+    error: ApiError;
+    /** The error, drawn as a card. */
+    content: string;
+};
+/**
+ * Turns anything a handler threw into the one shape it answers with.
+ *
+ * @param err The failure.
+ *        Anything that is not a `CardError` is treated as upstream's.
+ * @param renderOptions Colors the error card is drawn with;
+ *        omitted when it was a color that was rejected.
+ * @returns The rendered error.
+ */
+export declare const errorResult: (err: unknown, renderOptions?: ColorParams) => ApiResult;
+//# sourceMappingURL=api-result.d.ts.map

package/build/api/api-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-result.d.ts","sourceRoot":"","sources":["../../src/api/api-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAIpD;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,qBAAqB;IACrB,IAAI,EAAE,SAAS,CAAC;IAChB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GACjB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtC;IACE,MAAM,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,QAAQ,CAAC;IAChB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,OAAO,EAAE,gBAAgB,WAAW,KAAG,SAsBvE,CAAC"}

package/build/api/api-result.js

@@ -0,0 +1,33 @@
+import { CardError } from '../common/error.js';
+import { renderError } from '../common/render.js';
+/**
+ * Turns anything a handler threw into the one shape it answers with.
+ *
+ * @param err The failure.
+ *        Anything that is not a `CardError` is treated as upstream's.
+ * @param renderOptions Colors the error card is drawn with;
+ *        omitted when it was a color that was rejected.
+ * @returns The rendered error.
+ */
+export const errorResult = (err, renderOptions) => {
+    const error = CardError.from(err);
+    return {
+        status: 'error',
+        retryable: error.retryable,
+        error: {
+            code: error.code,
+            message: error.message,
+            secondaryMessage: error.secondaryMessage,
+            param: error.param,
+        },
+        content: renderError({
+            message: error.message,
+            secondaryMessage: error.secondaryMessage,
+            renderOptions: {
+                ...renderOptions,
+                // A missing param is the caller's to fix, so the card links its docs instead.
+                show_repo_link: error.code !== 'missing_param',
+            },
+        }),
+    };
+};

package/build/api/gist.d.ts

@@ -0,0 +1,29 @@
+import * as z from 'zod/mini';
+import type { CardConfig } from '../common/config.js';
+import type { ApiResult } from './api-result.js';
+import type { ApiQuery } from './params.js';
+/** What the gist endpoint accepts, on top of the shared color params. */
+declare const gistQuery: z.ZodMiniObject<{
+    id: z.ZodMiniType<string | undefined, string | undefined, z.core.$ZodTypeInternals<string | undefined, string | undefined>>;
+    border_radius: z.ZodMiniType<number | undefined, string | undefined, z.core.$ZodTypeInternals<number | undefined, string | undefined>>;
+    show_owner: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
+    browser_rendering: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
+    hide_border: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
+}, z.core.$strip>;
+/** The query this endpoint accepts, checked against the schema above. */
+type GistApiQuery = ApiQuery<typeof gistQuery>;
+/**
+ * Render the gist card for a set of query params.
+ *
+ * @param query Raw query params, plus any of the shared color params.
+ * @param query.id GitHub gist ID.
+ * @param query.border_radius Card border radius.
+ * @param query.show_owner Whether to show the gist owner.
+ * @param query.browser_rendering Whether the browser wraps the description text.
+ * @param query.hide_border Whether to hide the card border.
+ * @param config Deployment config supplying the PAT pool.
+ * @returns The rendered card, or a rendered error.
+ */
+export declare const gist: (query: GistApiQuery, config: CardConfig) => Promise<ApiResult>;
+export {};
+//# sourceMappingURL=gist.d.ts.map

package/build/api/gist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gist.d.ts","sourceRoot":"","sources":["../../src/api/gist.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAG9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C,yEAAyE;AACzE,QAAA,MAAM,SAAS;;;;;;iBAMb,CAAC;AAEH,yEAAyE;AACzE,KAAK,YAAY,GAAG,QAAQ,CAAC,OAAO,SAAS,CAAC,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,GAAU,OAAO,YAAY,EAAE,QAAQ,UAAU,KAAG,OAAO,CAAC,SAAS,CA8BrF,CAAC"}

package/build/api/gist.js

@@ -0,0 +1,52 @@
+import * as z from 'zod/mini';
+import { renderGistCard } from '../cards/gist.js';
+import { fetchGist } from '../fetchers/gist.js';
+import { errorResult } from './api-result.js';
+import { booleanParam, numberParam, parseColorParams, parseParams, safeParam } from './params.js';
+/** What the gist endpoint accepts, on top of the shared color params. */
+const gistQuery = z.object({
+    id: safeParam,
+    border_radius: numberParam,
+    show_owner: booleanParam,
+    browser_rendering: booleanParam,
+    hide_border: booleanParam,
+});
+/**
+ * Render the gist card for a set of query params.
+ *
+ * @param query Raw query params, plus any of the shared color params.
+ * @param query.id GitHub gist ID.
+ * @param query.border_radius Card border radius.
+ * @param query.show_owner Whether to show the gist owner.
+ * @param query.browser_rendering Whether the browser wraps the description text.
+ * @param query.hide_border Whether to hide the card border.
+ * @param config Deployment config supplying the PAT pool.
+ * @returns The rendered card, or a rendered error.
+ */
+export const gist = async (query, config) => {
+    let colors;
+    try {
+        colors = parseColorParams(query);
+    }
+    catch (err) {
+        // A rejected color cannot be used to draw its own error card.
+        return errorResult(err);
+    }
+    try {
+        const { id, border_radius, show_owner, browser_rendering, hide_border } = parseParams(gistQuery, query);
+        const gistData = await fetchGist({ id }, config);
+        return {
+            status: 'success',
+            content: renderGistCard(gistData, {
+                ...colors,
+                border_radius,
+                show_owner,
+                browser_rendering,
+                hide_border,
+            }),
+        };
+    }
+    catch (err) {
+        return errorResult(err, colors);
+    }
+};

package/build/api/index.d.ts

@@ -0,0 +1,13 @@
+export { gist } from './gist.js';
+export { pin } from './pin.js';
+export { stats } from './stats.js';
+export { topLangs } from './top-langs.js';
+export { wakatime } from './wakatime.js';
+export type { ApiError, ApiResult } from './api-result.js';
+export { CardConfig } from '../common/config.js';
+export type { CardConfigInit, PersonalAccessToken } from '../common/config.js';
+export type { FetchLike } from '../common/http.js';
+export type { ErrorCode } from '../common/error.js';
+export { themes } from '../themes/index.js';
+export type { ThemeName } from '../themes/index.js';
+//# sourceMappingURL=index.d.ts.map

package/build/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG3D,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC"}

package/build/api/index.js

@@ -0,0 +1,8 @@
+export { gist } from './gist.js';
+export { pin } from './pin.js';
+export { stats } from './stats.js';
+export { topLangs } from './top-langs.js';
+export { wakatime } from './wakatime.js';
+// every handler but `wakatime` needs the PAT pool, and that one still needs the transport.
+export { CardConfig } from '../common/config.js';
+export { themes } from '../themes/index.js';

package/build/api/params.d.ts

@@ -0,0 +1,93 @@
+import * as z from 'zod/mini';
+import type { ColorParams } from '../common/color.js';
+/**
+ * @file The api layer is the trust boundary:
+ * a query string arrives as strings, and each endpoint declares what it accepts as a schema over them.
+ * Parsing happens here once;
+ * the render functions are handed typed values and keep their own defaults.
+ *
+ * `zod/mini` rather than `zod`:
+ * this package ships to the browser, and the functional API tree-shakes down to the checks used below.
+ */
+/** Every param arrives as a string, or not at all. */
+declare const rawParam: z.ZodMiniOptional<z.ZodMiniString<string>>;
+/**
+ * `?x=true` / `?x=false`.
+ * Anything else is `undefined`, which leaves the card's own default in place.
+ */
+declare const booleanParam: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
+/** Comma-separated values, empty when the param is absent. */
+declare const listParam: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<string[], string | undefined>>;
+/**
+ * A number the card cannot fall back from, so a malformed one is rejected here:
+ * a render-time guard would throw into the generic catch and read as a temporary error.
+ *
+ * `parseFloat`, matching the coercion `Card` performs internally, so `?border_radius=10px` still renders `rx="10"`.
+ * Yields the parsed number, or `undefined` when the param is absent.
+ */
+declare const numberParam: z.ZodMiniType<number | undefined, string | undefined>;
+/**
+ * A number the card already falls back from — widths, counts, line heights:
+ * `NaN` reaches the renderer, which answers it with its own default.
+ */
+declare const looseIntParam: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<number | undefined, string | undefined>>;
+/**
+ * A four-digit year.
+ * Anything else builds a `DateTime` GitHub rejects, so it is a permanent error here rather than a failed request later.
+ * Yields the year, or `undefined` when the param is absent.
+ */
+declare const yearParam: z.ZodMiniType<number | undefined, string | undefined>;
+/**
+ * An id the fetchers put in a URL.
+ * Rejected before any request is made, and yielded unchanged otherwise.
+ */
+declare const safeParam: z.ZodMiniType<string | undefined, string | undefined>;
+/**
+ * A comma-separated list of ids, checked before it is split.
+ * The safe pattern allows the commas, so one check covers the whole list.
+ * Yields the split values, empty when the param is absent.
+ */
+declare const safeListParam: z.ZodMiniType<Array<string>, string | undefined>;
+/**
+ * A locale the cards have translations for.
+ * One wording for every endpoint:
+ * the message names the param, as the number and color rejections do.
+ */
+declare const localeParam: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<string | undefined, string | undefined>>;
+/**
+ * A param the card only renders as one of a fixed set of values.
+ *
+ * @param values The accepted values, as the card that renders them declares them.
+ * @returns Schema yielding one of `values`, or `undefined` when absent.
+ */
+declare const enumParam: <const T extends ReadonlyArray<string>>(values: T) => z.ZodMiniType<T[number] | undefined, string | undefined>;
+/**
+ * The query an endpoint accepts, derived from its own schema.
+ * Every param is optional and every value a string, which is all a query string can carry;
+ * naming it lets a consumer typecheck the object it builds.
+ */
+type ApiQuery<TSchema extends z.ZodMiniType> = Partial<z.input<TSchema>> & ColorParams;
+/**
+ * Runs a query through an endpoint's schema.
+ *
+ * Only the first rejection is reported:
+ * the error card has room for one line.
+ *
+ * @param schema The endpoint's schema.
+ * @param query Raw query params.
+ * @returns The parsed params.
+ * @throws {CardError} When the schema rejects a param.
+ */
+declare const parseParams: <TSchema extends z.ZodMiniType>(schema: TSchema, query: unknown) => z.output<TSchema>;
+/**
+ * The color params, validated.
+ * Split from the endpoint's own schema because a rejected color cannot then be used to render its own error card.
+ *
+ * @param query Raw query params.
+ * @returns The color params.
+ * @throws {CardError} When a param does not hold a color or a gradient.
+ */
+declare const parseColorParams: (query: unknown) => ColorParams;
+export type { ApiQuery };
+export { booleanParam, enumParam, listParam, localeParam, looseIntParam, numberParam, parseColorParams, parseParams, rawParam, safeListParam, safeParam, yearParam, };
+//# sourceMappingURL=params.d.ts.map

package/build/api/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../src/api/params.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMtD;;;;;;;;GAQG;AAEH,sDAAsD;AACtD,QAAA,MAAM,QAAQ,4CAAyB,CAAC;AAkCxC;;;GAGG;AACH,QAAA,MAAM,YAAY,wHAIjB,CAAC;AAEF,8DAA8D;AAC9D,QAAA,MAAM,SAAS,6GAA4C,CAAC;AAE5D;;;;;;GAMG;AACH,QAAA,MAAM,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,SAAS,EAAE,MAAM,GAAG,SAAS,CAGtE,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,aAAa,uHAGlB,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,SAAS,EAAE,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,SAAS,EAAE,MAAM,GAAG,SAAS,CAGpE,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,SAAS,EAAE,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,SAAS,EAAE,MAAM,GAAG,SAAS,CAEpE,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,aAAa,EAAE,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAGnE,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,WAAW,uHAGhB,CAAC;AAEF;;;;;GAKG;AACH,QAAA,MAAM,SAAS,GAAI,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,EACtD,QAAQ,CAAC,KACR,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,EAAE,MAAM,GAAG,SAAS,CACqC,CAAC;AAmBhG;;;;GAIG;AACH,KAAK,QAAQ,CAAC,OAAO,SAAS,CAAC,CAAC,WAAW,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,WAAW,CAAC;AAevF;;;;;;;;;;GAUG;AACH,QAAA,MAAM,WAAW,GAAI,OAAO,SAAS,CAAC,CAAC,WAAW,EAChD,QAAQ,OAAO,EACf,OAAO,OAAO,KACb,CAAC,CAAC,MAAM,CAAC,OAAO,CAMlB,CAAC;AAEF;;;;;;;GAOG;AACH,QAAA,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,WAAoD,CAAC;AAEhG,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB,OAAO,EACL,YAAY,EACZ,SAAS,EACT,SAAS,EACT,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,aAAa,EACb,SAAS,EACT,SAAS,GACV,CAAC"}

package/build/api/params.js

@@ -0,0 +1,145 @@
+import * as z from 'zod/mini';
+import { COLOR_PARAM_KEYS, THEME_PARAM_KEYS, isValidColorInput } from '../common/color.js';
+import { CardError } from '../common/error.js';
+import { parseArray, parseBoolean } from '../common/ops.js';
+import { isLocaleAvailable } from '../translations.js';
+/**
+ * @file The api layer is the trust boundary:
+ * a query string arrives as strings, and each endpoint declares what it accepts as a schema over them.
+ * Parsing happens here once;
+ * the render functions are handed typed values and keep their own defaults.
+ *
+ * `zod/mini` rather than `zod`:
+ * this package ships to the browser, and the functional API tree-shakes down to the checks used below.
+ */
+/** Every param arrives as a string, or not at all. */
+const rawParam = z.optional(z.string());
+/** Characters a username, repository, owner or gist id may contain. */
+const SAFE_PATTERN = /^[-\w/.,]+$/;
+/**
+ * Every rejection the api can put on an error card, in one place.
+ * The param comes from the issue's own path, so no schema repeats its own name.
+ */
+const REJECTION_MESSAGES = {
+    number: (param) => `Invalid number input for parameter "${param}"`,
+    year: (param) => `Invalid number input for parameter "${param}"`,
+    unsafe: (param) => `Parameter "${param}" contains unsafe characters`,
+    locale: () => 'Locale not found',
+    enum: (param) => `Incorrect ${param} input`,
+    color: (param) => `Invalid color input for parameter "${param}"`,
+};
+/**
+ * A check that words its own rejection:
+ * the message is built from the kind and the param's path rather than passed in.
+ *
+ * @param kind What the check rejects the param for.
+ * @param passes Whether a value is acceptable.
+ * @returns The check, ready for `.check()`.
+ */
+const rejects = (kind, passes) => z.refine((value) => typeof value !== 'string' || passes(value), {
+    error: (issue) => REJECTION_MESSAGES[kind](String(issue.path?.[0] ?? '')),
+});
+/**
+ * `?x=true` / `?x=false`.
+ * Anything else is `undefined`, which leaves the card's own default in place.
+ */
+const booleanParam = z.pipe(rawParam, 
+// Narrowed: `parseBoolean` also takes booleans, which a query string cannot hold.
+z.transform((value) => parseBoolean(value)));
+/** Comma-separated values, empty when the param is absent. */
+const listParam = z.pipe(rawParam, z.transform(parseArray));
+/**
+ * A number the card cannot fall back from, so a malformed one is rejected here:
+ * a render-time guard would throw into the generic catch and read as a temporary error.
+ *
+ * `parseFloat`, matching the coercion `Card` performs internally, so `?border_radius=10px` still renders `rx="10"`.
+ * Yields the parsed number, or `undefined` when the param is absent.
+ */
+const numberParam = z.pipe(rawParam.check(rejects('number', (value) => Number.isFinite(parseFloat(value)))), z.transform((value) => (value === undefined ? undefined : parseFloat(value))));
+/**
+ * A number the card already falls back from — widths, counts, line heights:
+ * `NaN` reaches the renderer, which answers it with its own default.
+ */
+const looseIntParam = z.pipe(rawParam, z.transform((value) => (value === undefined ? undefined : parseInt(value, 10))));
+/**
+ * A four-digit year.
+ * Anything else builds a `DateTime` GitHub rejects, so it is a permanent error here rather than a failed request later.
+ * Yields the year, or `undefined` when the param is absent.
+ */
+const yearParam = z.pipe(rawParam.check(rejects('year', (value) => /^\d{4}$/.test(value))), z.transform((value) => (value === undefined ? undefined : Number(value))));
+/**
+ * An id the fetchers put in a URL.
+ * Rejected before any request is made, and yielded unchanged otherwise.
+ */
+const safeParam = rawParam.check(rejects('unsafe', (value) => !value || SAFE_PATTERN.test(value)));
+/**
+ * A comma-separated list of ids, checked before it is split.
+ * The safe pattern allows the commas, so one check covers the whole list.
+ * Yields the split values, empty when the param is absent.
+ */
+const safeListParam = z.pipe(safeParam, z.transform(parseArray));
+/**
+ * A locale the cards have translations for.
+ * One wording for every endpoint:
+ * the message names the param, as the number and color rejections do.
+ */
+const localeParam = z.pipe(rawParam.check(rejects('locale', (value) => !value || isLocaleAvailable(value))), z.transform((value) => value?.toLowerCase()));
+/**
+ * A param the card only renders as one of a fixed set of values.
+ *
+ * @param values The accepted values, as the card that renders them declares them.
+ * @returns Schema yielding one of `values`, or `undefined` when absent.
+ */
+const enumParam = (values) => rawParam.check(rejects('enum', (value) => values.includes(value)));
+/**
+ * Every color param an endpoint accepts, validated and picked in one pass.
+ *
+ * Theme params are `rawParam`:
+ * they name a theme, and an unknown name falls back to the default rather than being an error.
+ */
+const colorParamsSchema = z.object(Object.fromEntries(COLOR_PARAM_KEYS.map((key) => [
+    key,
+    THEME_PARAM_KEYS.includes(key)
+        ? rawParam
+        : rawParam.check(rejects('color', isValidColorInput)),
+])));
+/**
+ * Turns a rejection back into the error the api answers with.
+ * Every rejection is the query's fault, so they share one code
+ * and differ only in the message the check already worded.
+ *
+ * @param error What the schema rejected.
+ * @returns The failure, ready to render.
+ */
+const toCardError = (error) => {
+    const issue = error.issues[0];
+    return CardError.invalidParam(String(issue?.path[0] ?? ''), issue?.message ?? 'Invalid input');
+};
+/**
+ * Runs a query through an endpoint's schema.
+ *
+ * Only the first rejection is reported:
+ * the error card has room for one line.
+ *
+ * @param schema The endpoint's schema.
+ * @param query Raw query params.
+ * @returns The parsed params.
+ * @throws {CardError} When the schema rejects a param.
+ */
+const parseParams = (schema, query) => {
+    const result = z.safeParse(schema, query);
+    if (!result.success) {
+        throw toCardError(result.error);
+    }
+    return result.data;
+};
+/**
+ * The color params, validated.
+ * Split from the endpoint's own schema because a rejected color cannot then be used to render its own error card.
+ *
+ * @param query Raw query params.
+ * @returns The color params.
+ * @throws {CardError} When a param does not hold a color or a gradient.
+ */
+const parseColorParams = (query) => parseParams(colorParamsSchema, query);
+export { booleanParam, enumParam, listParam, localeParam, looseIntParam, numberParam, parseColorParams, parseParams, rawParam, safeListParam, safeParam, yearParam, };

package/build/api/pin.d.ts

@@ -0,0 +1,47 @@
+import * as z from 'zod/mini';
+import type { CardConfig } from '../common/config.js';
+import type { ApiResult } from './api-result.js';
+import type { ApiQuery } from './params.js';
+/** What the pin endpoint accepts, on top of the shared color params. */
+declare const pinQuery: z.ZodMiniObject<{
+    username: z.ZodMiniType<string | undefined, string | undefined, z.core.$ZodTypeInternals<string | undefined, string | undefined>>;
+    repo: z.ZodMiniType<string | undefined, string | undefined, z.core.$ZodTypeInternals<string | undefined, string | undefined>>;
+    hide_border: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
+    card_width: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<number | undefined, string | undefined>>;
+    show_owner: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
+    browser_rendering: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
+    show: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<string[], string | undefined>>;
+    show_icons: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
+    number_format: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    text_bold: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
+    line_height: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    locale: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<string | undefined, string | undefined>>;
+    border_radius: z.ZodMiniType<number | undefined, string | undefined, z.core.$ZodTypeInternals<number | undefined, string | undefined>>;
+    description_lines_count: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<number | undefined, string | undefined>>;
+}, z.core.$strip>;
+/** The query this endpoint accepts, checked against the schema above. */
+type PinApiQuery = ApiQuery<typeof pinQuery>;
+/**
+ * Render the repository card for a set of query params.
+ *
+ * @param query Raw query params, plus any of the shared color params.
+ * @param query.username GitHub username the repository belongs to.
+ * @param query.repo Repository name.
+ * @param query.hide_border Whether to hide the card border.
+ * @param query.card_width Card width.
+ * @param query.show_owner Whether to show the repository owner.
+ * @param query.browser_rendering Whether the browser wraps the description text.
+ * @param query.show Comma-separated extra stats to show.
+ * @param query.show_icons Whether to show the stat icons.
+ * @param query.number_format How numbers are abbreviated.
+ * @param query.text_bold Whether the stat values are bold.
+ * @param query.line_height Line height between the stats.
+ * @param query.locale Language the card is rendered in.
+ * @param query.border_radius Card border radius.
+ * @param query.description_lines_count Lines the description is wrapped to.
+ * @param config Deployment config supplying the PAT pool.
+ * @returns The rendered card, or a rendered error.
+ */
+export declare const pin: (query: PinApiQuery, config: CardConfig) => Promise<ApiResult>;
+export {};
+//# sourceMappingURL=pin.d.ts.map