@stats-forge/github-stats-forge-core 0.0.2 → 0.1.0

package/README.md

@@ -100,16 +100,6 @@ const config = new CardConfig({
 });
 ```
 
-## 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.

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

@@ -1,5 +1,5 @@
-import type { ColorParams } from '../common/color.js';
-import type { ErrorCode } from '../common/error.js';
+import type { ColorParams } from '../common/color.ts';
+import type { ErrorCode } from '../common/error.ts';
 /**
  * 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`,
@@ -33,12 +33,11 @@ export type ApiResult = {
 };
 /**
  * Turns anything a handler threw into the one shape it answers with.
+ * Anything that is not a `CardError` is treated as upstream's.
  *
- * @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;
+export declare const errorResult: (err: unknown, 
+/** omitted when it was a color that was rejected, which cannot draw its own error card */
+renderOptions?: ColorParams) => ApiResult;
 //# sourceMappingURL=api-result.d.ts.map

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

@@ -1 +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"}
+{"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;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QACjB,OAAO;AACZ,0FAA0F;gBAC1E,WAAW,KAC1B,SAsBF,CAAC"}

package/build/api/api-result.js

@@ -2,14 +2,13 @@ import { CardError } from '../common/error.js';
 import { renderError } from '../common/render.js';
 /**
  * Turns anything a handler threw into the one shape it answers with.
+ * Anything that is not a `CardError` is treated as upstream's.
  *
- * @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) => {
+export const errorResult = (err, 
+/** omitted when it was a color that was rejected, which cannot draw its own error card */
+renderOptions) => {
     const error = CardError.from(err);
     return {
         status: 'error',

package/build/api/gist.d.ts

@@ -1,7 +1,7 @@
 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';
+import type { CardConfig } from '../common/config.ts';
+import type { ApiResult } from './api-result.ts';
+import type { ApiQuery } from './params.ts';
 /** 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>>;
@@ -15,13 +15,6 @@ 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>;

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

@@ -1 +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"}
+{"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;;;;GAIG;AACH,eAAO,MAAM,IAAI,UAAiB,YAAY,UAAU,UAAU,KAAG,OAAO,CAAC,SAAS,CA8BrF,CAAC"}

package/build/api/gist.js

@@ -14,13 +14,6 @@ const gistQuery = z.object({
 /**
  * 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) => {
@@ -28,9 +21,9 @@ export const gist = async (query, config) => {
     try {
         colors = parseColorParams(query);
     }
-    catch (err) {
+    catch (error) {
         // A rejected color cannot be used to draw its own error card.
-        return errorResult(err);
+        return errorResult(error);
     }
     try {
         const { id, border_radius, show_owner, browser_rendering, hide_border } = parseParams(gistQuery, query);
@@ -46,7 +39,7 @@ export const gist = async (query, config) => {
             }),
         };
     }
-    catch (err) {
-        return errorResult(err, colors);
+    catch (error) {
+        return errorResult(error, colors);
     }
 };

package/build/api/index.d.ts

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

package/build/api/params.d.ts

@@ -1,5 +1,5 @@
 import * as z from 'zod/mini';
-import type { ColorParams } from '../common/color.js';
+import type { ColorParams } from '../common/color.ts';
 /**
  * @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.
@@ -42,6 +42,11 @@ declare const yearParam: z.ZodMiniType<number | undefined, string | undefined>;
  * Rejected before any request is made, and yielded unchanged otherwise.
  */
 declare const safeParam: z.ZodMiniType<string | undefined, string | undefined>;
+/**
+ * A GitHub login, stricter than `safeParam`: no leading, trailing or doubled hyphen.
+ * Rejected here so a malformed one is a permanent error rather than the NOT_FOUND GitHub answers.
+ */
+declare const usernameParam: 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.
@@ -57,7 +62,6 @@ declare const localeParam: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<strin
 /**
  * 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>;
@@ -73,21 +77,20 @@ type ApiQuery<TSchema extends z.ZodMiniType> = Partial<z.input<TSchema>> & Color
  * 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.
+ *
+ * @returns The parsed params.
  */
 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.
+ *
+ * @returns The color params.
  */
 declare const parseColorParams: (query: unknown) => ColorParams;
 export type { ApiQuery };
-export { booleanParam, enumParam, listParam, localeParam, looseIntParam, numberParam, parseColorParams, parseParams, rawParam, safeListParam, safeParam, yearParam, };
+export { booleanParam, enumParam, listParam, localeParam, looseIntParam, numberParam, parseColorParams, parseParams, rawParam, safeListParam, safeParam, usernameParam, yearParam, };
 //# sourceMappingURL=params.d.ts.map

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

@@ -1 +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"}
+{"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;AAOtD;;;;;;;;GAQG;AAEH,sDAAsD;AACtD,QAAA,MAAM,QAAQ,4CAAyB,CAAC;AAiCxC;;;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;;;GAGG;AACH,QAAA,MAAM,aAAa,EAAE,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,SAAS,EAAE,MAAM,GAAG,SAAS,CAExE,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;;;;GAIG;AACH,QAAA,MAAM,SAAS,GAAI,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,UAC9C,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;AAcvF;;;;;;;;;GASG;AACH,QAAA,MAAM,WAAW,GAAI,OAAO,SAAS,CAAC,CAAC,WAAW,UACxC,OAAO,SACR,OAAO,KACb,CAAC,CAAC,MAAM,CAAC,OAAO,CAMlB,CAAC;AAEF;;;;;;;GAOG;AACH,QAAA,MAAM,gBAAgB,UAAW,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,aAAa,EACb,SAAS,GACV,CAAC"}

package/build/api/params.js

@@ -1,5 +1,6 @@
 import * as z from 'zod/mini';
 import { COLOR_PARAM_KEYS, THEME_PARAM_KEYS, isValidColorInput } from '../common/color.js';
+import { GITHUB_USERNAME_PATTERN } from '../common/constants.js';
 import { CardError } from '../common/error.js';
 import { parseArray, parseBoolean } from '../common/ops.js';
 import { isLocaleAvailable } from '../translations.js';
@@ -14,7 +15,7 @@ import { isLocaleAvailable } from '../translations.js';
  */
 /** 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. */
+/** Characters a repository, owner or gist id may contain. */
 const SAFE_PATTERN = /^[-\w/.,]+$/;
 /**
  * Every rejection the api can put on an error card, in one place.
@@ -24,6 +25,7 @@ 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`,
+    username: (param) => `Invalid username input for parameter "${param}"`,
     locale: () => 'Locale not found',
     enum: (param) => `Incorrect ${param} input`,
     color: (param) => `Invalid color input for parameter "${param}"`,
@@ -32,8 +34,6 @@ const REJECTION_MESSAGES = {
  * 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), {
@@ -55,12 +55,12 @@ const listParam = z.pipe(rawParam, z.transform(parseArray));
  * `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))));
+const numberParam = z.pipe(rawParam.check(rejects('number', (value) => Number.isFinite(Number.parseFloat(value)))), z.transform((value) => (value === undefined ? undefined : Number.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))));
+const looseIntParam = z.pipe(rawParam, z.transform((value) => (value === undefined ? undefined : Number.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.
@@ -72,6 +72,11 @@ const yearParam = z.pipe(rawParam.check(rejects('year', (value) => /^\d{4}$/.tes
  * Rejected before any request is made, and yielded unchanged otherwise.
  */
 const safeParam = rawParam.check(rejects('unsafe', (value) => !value || SAFE_PATTERN.test(value)));
+/**
+ * A GitHub login, stricter than `safeParam`: no leading, trailing or doubled hyphen.
+ * Rejected here so a malformed one is a permanent error rather than the NOT_FOUND GitHub answers.
+ */
+const usernameParam = rawParam.check(rejects('username', (value) => !value || GITHUB_USERNAME_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.
@@ -87,7 +92,6 @@ const localeParam = z.pipe(rawParam.check(rejects('locale', (value) => !value ||
 /**
  * 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)));
@@ -108,11 +112,10 @@ const colorParamsSchema = z.object(Object.fromEntries(COLOR_PARAM_KEYS.map((key)
  * 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];
+    const [issue] = error.issues;
     return CardError.invalidParam(String(issue?.path[0] ?? ''), issue?.message ?? 'Invalid input');
 };
 /**
@@ -121,10 +124,9 @@ const toCardError = (error) => {
  * 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.
+ *
+ * @returns The parsed params.
  */
 const parseParams = (schema, query) => {
     const result = z.safeParse(schema, query);
@@ -137,9 +139,9 @@ const parseParams = (schema, query) => {
  * 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.
+ *
+ * @returns The color params.
  */
 const parseColorParams = (query) => parseParams(colorParamsSchema, query);
-export { booleanParam, enumParam, listParam, localeParam, looseIntParam, numberParam, parseColorParams, parseParams, rawParam, safeListParam, safeParam, yearParam, };
+export { booleanParam, enumParam, listParam, localeParam, looseIntParam, numberParam, parseColorParams, parseParams, rawParam, safeListParam, safeParam, usernameParam, yearParam, };

package/build/api/pin.d.ts

@@ -1,7 +1,7 @@
 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';
+import type { CardConfig } from '../common/config.ts';
+import type { ApiResult } from './api-result.ts';
+import type { ApiQuery } from './params.ts';
 /** 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>>;
@@ -24,22 +24,6 @@ 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>;

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

@@ -1 +1 @@
-{"version":3,"file":"pin.d.ts","sourceRoot":"","sources":["../../src/api/pin.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;AAa5C,wEAAwE;AACxE,QAAA,MAAM,QAAQ;;;;;;;;;;;;;;;iBAeZ,CAAC;AAEH,yEAAyE;AACzE,KAAK,WAAW,GAAG,QAAQ,CAAC,OAAO,QAAQ,CAAC,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,GAAG,GAAU,OAAO,WAAW,EAAE,QAAQ,UAAU,KAAG,OAAO,CAAC,SAAS,CA8DnF,CAAC"}
+{"version":3,"file":"pin.d.ts","sourceRoot":"","sources":["../../src/api/pin.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;AAc5C,wEAAwE;AACxE,QAAA,MAAM,QAAQ;;;;;;;;;;;;;;;iBAeZ,CAAC;AAEH,yEAAyE;AACzE,KAAK,WAAW,GAAG,QAAQ,CAAC,OAAO,QAAQ,CAAC,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,GAAG,UAAiB,WAAW,UAAU,UAAU,KAAG,OAAO,CAAC,SAAS,CA8DnF,CAAC"}

package/build/api/pin.js

@@ -2,10 +2,10 @@ import * as z from 'zod/mini';
 import { renderRepoCard } from '../cards/repo.js';
 import { fetchRepo } from '../fetchers/repo.js';
 import { errorResult } from './api-result.js';
-import { booleanParam, listParam, localeParam, looseIntParam, numberParam, parseColorParams, parseParams, rawParam, safeParam, } from './params.js';
+import { booleanParam, listParam, localeParam, looseIntParam, numberParam, parseColorParams, parseParams, rawParam, safeParam, usernameParam, } from './params.js';
 /** What the pin endpoint accepts, on top of the shared color params. */
 const pinQuery = z.object({
-    username: safeParam,
+    username: usernameParam,
     repo: safeParam,
     hide_border: booleanParam,
     card_width: looseIntParam,
@@ -23,22 +23,6 @@ const pinQuery = z.object({
 /**
  * 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 const pin = async (query, config) => {
@@ -46,9 +30,9 @@ export const pin = async (query, config) => {
     try {
         colors = parseColorParams(query);
     }
-    catch (err) {
+    catch (error) {
         // A rejected color cannot be used to draw its own error card.
-        return errorResult(err);
+        return errorResult(error);
     }
     try {
         const { username, repo, hide_border, card_width, show_owner, browser_rendering, show, show_icons, number_format, text_bold, line_height, locale, border_radius, description_lines_count, } = parseParams(pinQuery, query);
@@ -81,7 +65,7 @@ export const pin = async (query, config) => {
             }),
         };
     }
-    catch (err) {
-        return errorResult(err, colors);
+    catch (error) {
+        return errorResult(error, colors);
     }
 };

package/build/api/stats.d.ts

@@ -1,7 +1,7 @@
 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';
+import type { CardConfig } from '../common/config.ts';
+import type { ApiResult } from './api-result.ts';
+import type { ApiQuery } from './params.ts';
 /** What the stats endpoint accepts, on top of the shared color params. */
 declare const statsQuery: z.ZodMiniObject<{
     username: z.ZodMiniType<string | undefined, string | undefined, z.core.$ZodTypeInternals<string | undefined, string | undefined>>;
@@ -31,11 +31,17 @@ declare const statsQuery: z.ZodMiniObject<{
 }, z.core.$strip>;
 /** The query this endpoint accepts, checked against the schema above. */
 type StatsApiQuery = ApiQuery<typeof statsQuery>;
+/**
+ * Render the stats card for a set of query params.
+ *
+ * @returns The rendered card, or a rendered error.
+ */
+declare const renderStats: (query: StatsApiQuery, config: CardConfig) => Promise<ApiResult>;
 /**
  * The card, with the values its enum params accept.
  * A UI reads them off the function it calls, e.g. `stats.LAYOUTS`.
  */
-export declare const stats: ((query: StatsApiQuery, config: CardConfig) => Promise<ApiResult>) & {
+export declare const stats: typeof renderStats & {
     RANK_ICONS: readonly ["default", "github", "percentile"];
 };
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../src/api/stats.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;AAgB5C,0EAA0E;AAC1E,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;iBAyBd,CAAC;AAEH,yEAAyE;AACzE,KAAK,aAAa,GAAG,QAAQ,CAAC,OAAO,UAAU,CAAC,CAAC;AAuIjD;;;GAGG;AACH,eAAO,MAAM,KAAK,WA1GgB,aAAa,UAAU,UAAU,KAAG,OAAO,CAAC,SAAS,CAAC;;CA4GtF,CAAC"}
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../src/api/stats.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;AAgB5C,0EAA0E;AAC1E,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;iBAyBd,CAAC;AAEH,yEAAyE;AACzE,KAAK,aAAa,GAAG,QAAQ,CAAC,OAAO,UAAU,CAAC,CAAC;AAEjD;;;;GAIG;AACH,QAAA,MAAM,WAAW,UAAiB,aAAa,UAAU,UAAU,KAAG,OAAO,CAAC,SAAS,CAoGtF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,KAAK;;CAEhB,CAAC"}

package/build/api/stats.js

@@ -2,10 +2,10 @@ import * as z from 'zod/mini';
 import { RANK_ICONS, renderStatsCard } from '../cards/stats.js';
 import { fetchStats } from '../fetchers/stats.js';
 import { errorResult } from './api-result.js';
-import { booleanParam, enumParam, listParam, localeParam, looseIntParam, numberParam, parseColorParams, parseParams, rawParam, safeListParam, safeParam, yearParam, } from './params.js';
+import { booleanParam, enumParam, listParam, localeParam, looseIntParam, numberParam, parseColorParams, parseParams, rawParam, safeListParam, usernameParam, yearParam, } from './params.js';
 /** What the stats endpoint accepts, on top of the shared color params. */
 const statsQuery = z.object({
-    username: safeParam,
+    username: usernameParam,
     repo: safeListParam,
     owner: safeListParam,
     hide: listParam,
@@ -33,32 +33,6 @@ const statsQuery = z.object({
 /**
  * Render the stats card for a set of query params.
  *
- * @param query Raw query params, plus any of the shared color params.
- * @param query.username GitHub username.
- * @param query.repo Comma-separated repositories the search-based stats are scoped to.
- * @param query.owner Comma-separated owners the search-based stats are scoped to.
- * @param query.hide Comma-separated stats to hide.
- * @param query.hide_title Whether to hide the card title.
- * @param query.hide_border Whether to hide the card border.
- * @param query.card_width Card width.
- * @param query.hide_rank Whether to hide the rank circle.
- * @param query.show_icons Whether to show the stat icons.
- * @param query.include_all_commits Whether to count commits of all time.
- * @param query.commits_year Year the commits are counted for.
- * @param query.line_height Line height between the stats.
- * @param query.text_bold Whether the stat values are bold.
- * @param query.exclude_repo Comma-separated repositories to exclude.
- * @param query.custom_title Card title.
- * @param query.locale Language the card is rendered in.
- * @param query.disable_animations Whether to disable the card animations.
- * @param query.border_radius Card border radius.
- * @param query.number_format How numbers are abbreviated.
- * @param query.role Comma-separated owner affiliations to include.
- * @param query.number_precision Decimals kept when a number is abbreviated.
- * @param query.rank_icon Which rank indicator to draw.
- * @param query.show Comma-separated extra stats to show.
- * @param query.contribs_include_own_repos Whether the contributed-to counts include the user's own repositories.
- * @param config Deployment config supplying the PAT pool.
  * @returns The rendered card, or a rendered error.
  */
 const renderStats = async (query, config) => {
@@ -66,9 +40,9 @@ const renderStats = async (query, config) => {
     try {
         colors = parseColorParams(query);
     }
-    catch (err) {
+    catch (error) {
         // A rejected color cannot be used to draw its own error card.
-        return errorResult(err);
+        return errorResult(error);
     }
     try {
         const { username, repo, owner, hide, hide_title, hide_border, card_width, hide_rank, show_icons, include_all_commits, commits_year, line_height, text_bold, exclude_repo, custom_title, locale, disable_animations, border_radius, number_format, role, number_precision, rank_icon, show, contribs_include_own_repos, } = parseParams(statsQuery, query);
@@ -119,8 +93,8 @@ const renderStats = async (query, config) => {
             }, username, repository, owner),
         };
     }
-    catch (err) {
-        return errorResult(err, colors);
+    catch (error) {
+        return errorResult(error, colors);
     }
 };
 /**

package/build/api/top-langs.d.ts

@@ -1,7 +1,7 @@
 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';
+import type { CardConfig } from '../common/config.ts';
+import type { ApiResult } from './api-result.ts';
+import type { ApiQuery } from './params.ts';
 /** What the top-languages endpoint accepts, on top of the shared color params. */
 declare const topLangsQuery: z.ZodMiniObject<{
     username: z.ZodMiniType<string | undefined, string | undefined, z.core.$ZodTypeInternals<string | undefined, string | undefined>>;
@@ -9,7 +9,7 @@ declare const topLangsQuery: z.ZodMiniObject<{
     hide_title: 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>>;
     card_width: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<number | undefined, string | undefined>>;
-    layout: z.ZodMiniType<"compact" | "normal" | "donut" | "donut-vertical" | "pie" | undefined, string | undefined, z.core.$ZodTypeInternals<"compact" | "normal" | "donut" | "donut-vertical" | "pie" | undefined, string | undefined>>;
+    layout: z.ZodMiniType<"compact" | "donut" | "donut-vertical" | "normal" | "pie" | undefined, string | undefined, z.core.$ZodTypeInternals<"compact" | "donut" | "donut-vertical" | "normal" | "pie" | undefined, string | undefined>>;
     langs_count: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<number | undefined, string | undefined>>;
     exclude_repo: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<string[], string | undefined>>;
     size_weight: z.ZodMiniType<number | undefined, string | undefined, z.core.$ZodTypeInternals<number | undefined, string | undefined>>;
@@ -21,15 +21,21 @@ declare const topLangsQuery: z.ZodMiniObject<{
     disable_animations: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
     hide_progress: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
     hide_values: z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniString<string>>, z.ZodMiniTransform<boolean | undefined, string | undefined>>;
-    stats_format: z.ZodMiniType<"percentages" | "bytes" | undefined, string | undefined, z.core.$ZodTypeInternals<"percentages" | "bytes" | undefined, string | undefined>>;
+    stats_format: z.ZodMiniType<"bytes" | "percentages" | undefined, string | undefined, z.core.$ZodTypeInternals<"bytes" | "percentages" | undefined, string | undefined>>;
 }, z.core.$strip>;
 /** The query this endpoint accepts, checked against the schema above. */
 type TopLangsApiQuery = ApiQuery<typeof topLangsQuery>;
+/**
+ * Render the top languages card for a set of query params.
+ *
+ * @returns The rendered card, or a rendered error.
+ */
+declare const renderTopLangs: (query: TopLangsApiQuery, config: CardConfig) => Promise<ApiResult>;
 /**
  * The card, with the values its enum params accept.
  * A UI reads them off the function it calls, e.g. `topLangs.LAYOUTS`.
  */
-export declare const topLangs: ((query: TopLangsApiQuery, config: CardConfig) => Promise<ApiResult>) & {
+export declare const topLangs: typeof renderTopLangs & {
     LAYOUTS: readonly ["compact", "normal", "donut", "donut-vertical", "pie"];
     STATS_FORMATS: readonly ["percentages", "bytes"];
 };

package/build/api/top-langs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"top-langs.d.ts","sourceRoot":"","sources":["../../src/api/top-langs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAO9B,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;AAc5C,kFAAkF;AAClF,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;iBAmBjB,CAAC;AAEH,yEAAyE;AACzE,KAAK,gBAAgB,GAAG,QAAQ,CAAC,OAAO,aAAa,CAAC,CAAC;AA6FvD;;;GAGG;AACH,eAAO,MAAM,QAAQ,WAtEgB,gBAAgB,UAAU,UAAU,KAAG,OAAO,CAAC,SAAS,CAAC;;;CAyE5F,CAAC"}
+{"version":3,"file":"top-langs.d.ts","sourceRoot":"","sources":["../../src/api/top-langs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAO9B,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;AAc5C,kFAAkF;AAClF,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;iBAmBjB,CAAC;AAEH,yEAAyE;AACzE,KAAK,gBAAgB,GAAG,QAAQ,CAAC,OAAO,aAAa,CAAC,CAAC;AAEvD;;;;GAIG;AACH,QAAA,MAAM,cAAc,UAAiB,gBAAgB,UAAU,UAAU,KAAG,OAAO,CAAC,SAAS,CAgE5F,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,QAAQ;;;CAGnB,CAAC"}