@takuhon/activity 0.12.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Takuhon contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,10 @@
+@takuhon/core
+Copyright 2026 Takuhon contributors
+
+This product includes software developed by the Takuhon project
+(https://github.com/takuhon-dev/takuhon).
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Third-party dependencies retain their own licenses; see this package's
+node_modules listing for details.

package/README.md

@@ -0,0 +1,46 @@
+# @takuhon/activity
+
+Developer-activity fetchers for [takuhon](https://github.com/takuhon-dev/takuhon).
+
+This package reads the profile owner's configured **GitHub** and **WakaTime**
+activity and assembles an `ActivitySnapshot` (the shape defined by
+`@takuhon/core`). It performs the network I/O that `@takuhon/core` deliberately
+does not, and reuses core's pure transforms to shape the result.
+
+A sync step — the `takuhon activity sync` CLI command or a Cloudflare scheduled
+(cron) job — calls `fetchActivitySnapshot`, then persists the snapshot through
+an `ActivityStorage`. Rendering then reads the stored snapshot statically; the
+public render path never calls these APIs.
+
+## Usage
+
+```ts
+import { fetchActivitySnapshot } from '@takuhon/activity';
+
+const snapshot = await fetchActivitySnapshot(
+  takuhon.settings.activity, // owner-curated config from takuhon.json
+  {
+    githubToken: process.env.TAKUHON_GITHUB_TOKEN, // optional; required for contributions
+    wakatimeKey: process.env.TAKUHON_WAKATIME_KEY, // required for coding time
+  },
+  { onError: (source, err) => console.warn(`activity sync: ${source} failed`, err) },
+);
+```
+
+Each source degrades gracefully: one that is disabled, unconfigured, missing
+its secret, or failing is simply omitted (reported via `onError`) rather than
+failing the whole snapshot. `isEmptySnapshot(snapshot)` reports when nothing was
+gathered, so the caller can keep the last-known snapshot instead of overwriting
+it with an empty one.
+
+## Signals
+
+| Signal        | Source                                                    | Auth                                          |
+| ------------- | --------------------------------------------------------- | --------------------------------------------- |
+| Language %    | GitHub REST `repos/{owner}/{repo}/languages` (aggregated) | Optional token (raises rate limit)            |
+| Contributions | GitHub GraphQL `contributionsCollection`                  | **Token required** (calendar is GraphQL-only) |
+| Coding time   | WakaTime `users/{user}/stats/{range}`                     | **API key required**                          |
+
+Secrets are provided per sync run and never stored in `takuhon.json` or the
+snapshot. The `fetch` implementation is injectable for testing; it defaults to
+the runtime global (Node 22+ / Cloudflare Workers).

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import { ActivitySettings, ActivitySnapshot, ContributionCalendar } from '@takuhon/core';
+
+/**
+ * Build an {@link ActivitySnapshot} from the owner's configured sources.
+ *
+ * Each source is fetched independently and degrades gracefully: a source that
+ * is disabled, unconfigured, missing its secret, or failing is simply omitted
+ * (its error is reported via {@link ActivityFetchDeps.onError}) rather than
+ * aborting the whole snapshot. The caller (a CLI command or scheduled job)
+ * decides what to do with a snapshot that gathered nothing — typically keeping
+ * the last-known one rather than overwriting it with an empty result.
+ *
+ * This module performs network I/O, so it lives outside `@takuhon/core` (which
+ * is platform-independent); it reuses core's pure transforms to shape the data.
+ */
+
+/** Secrets for the activity sources. Never persisted; supplied per sync run. */
+interface ActivitySecrets {
+    /** GitHub token. Optional for languages; REQUIRED for contributions. */
+    githubToken?: string;
+    /** WakaTime API key. REQUIRED to read coding time. */
+    wakatimeKey?: string;
+}
+interface ActivityFetchDeps {
+    /** HTTP client. Defaults to the runtime global `fetch` (Node 22+ / Workers). */
+    fetch?: typeof fetch;
+    /** Clock for `lastSyncedAt`; injectable for deterministic tests. */
+    now?: () => Date;
+    /** Reports a per-source failure so the caller can audit-log it. */
+    onError?: (source: 'github-languages' | 'github-contributions' | 'wakatime', err: unknown) => void;
+}
+/**
+ * Fetch and assemble the activity snapshot for the given config. Always
+ * resolves (never rejects): failures surface through `onError` and leave the
+ * corresponding field absent.
+ */
+declare function fetchActivitySnapshot(config: ActivitySettings, secrets?: ActivitySecrets, deps?: ActivityFetchDeps): Promise<ActivitySnapshot>;
+/** True when the snapshot carries no metric data (only `lastSyncedAt`). */
+declare function isEmptySnapshot(snapshot: ActivitySnapshot): boolean;
+
+/**
+ * GitHub fetchers for the activity snapshot.
+ *
+ * Two signals are read:
+ * - **Language bytes** via the REST `repos/{owner}/{repo}/languages` endpoint,
+ *   aggregated across the user's owned (non-fork) repositories. REST works
+ *   unauthenticated (at a low rate limit); a token raises the limit.
+ * - **Contribution calendar** via the GraphQL `contributionsCollection`. The
+ *   calendar is only exposed over GraphQL (the REST events API does not provide
+ *   it), so this REQUIRES a token.
+ *
+ * The `fetch` implementation is injected so tests can supply fakes; in
+ * production it defaults to the runtime global (Node 22+ / Workers).
+ */
+
+/** Default cap on repositories scanned for languages, to bound fan-out. */
+declare const DEFAULT_MAX_REPOS = 50;
+/** Thrown when a GitHub request fails; carries no token or host-path detail. */
+declare class GitHubFetchError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class GitHubClient {
+    private readonly fetchImpl;
+    constructor(fetchImpl?: typeof fetch);
+    /**
+     * Aggregate language byte counts across the user's owned, non-fork repos
+     * (capped at `maxRepos`, most-recently-pushed first). Returns raw bytes per
+     * language; the caller converts to percentages via `@takuhon/core`.
+     */
+    fetchLanguages(username: string, token?: string, maxRepos?: number): Promise<Record<string, number>>;
+    /**
+     * Read the trailing-year contribution calendar. Requires a token (the
+     * calendar is GraphQL-only).
+     */
+    fetchContributions(username: string, token: string): Promise<ContributionCalendar>;
+    private getJson;
+}
+
+/**
+ * WakaTime fetcher for the activity snapshot.
+ *
+ * Reads total coding seconds over a range from the `users/{user}/stats/{range}`
+ * endpoint. WakaTime has no unauthenticated mode, so an API key is REQUIRED; it
+ * is sent as HTTP Basic auth (the key base64-encoded) and only ever flows
+ * through this sync step — never into any stored document.
+ *
+ * The `fetch` implementation is injected for tests; production defaults to the
+ * runtime global.
+ */
+/** Default stats range — recent activity rather than all-time. */
+declare const DEFAULT_WAKATIME_RANGE = "last_year";
+/** Thrown when a WakaTime request fails; carries no key or host-path detail. */
+declare class WakaTimeFetchError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class WakaTimeClient {
+    private readonly fetchImpl;
+    constructor(fetchImpl?: typeof fetch);
+    /** Total coding seconds for `username` over `range` (default last year). */
+    fetchCodingSeconds(username: string, apiKey: string, range?: string): Promise<number>;
+}
+
+export { type ActivityFetchDeps, type ActivitySecrets, DEFAULT_MAX_REPOS, DEFAULT_WAKATIME_RANGE, GitHubClient, GitHubFetchError, WakaTimeClient, WakaTimeFetchError, fetchActivitySnapshot, isEmptySnapshot };

package/dist/index.js

@@ -0,0 +1,181 @@
+// src/fetch-snapshot.ts
+import {
+  computeLanguagePercentages,
+  deriveRankTier,
+  formatCodingTime
+} from "@takuhon/core";
+
+// src/github.ts
+var GITHUB_API = "https://api.github.com";
+var USER_AGENT = "takuhon-activity";
+var DEFAULT_MAX_REPOS = 50;
+var GitHubFetchError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "GitHubFetchError";
+  }
+};
+var GitHubClient = class {
+  constructor(fetchImpl = fetch) {
+    this.fetchImpl = fetchImpl;
+  }
+  fetchImpl;
+  /**
+   * Aggregate language byte counts across the user's owned, non-fork repos
+   * (capped at `maxRepos`, most-recently-pushed first). Returns raw bytes per
+   * language; the caller converts to percentages via `@takuhon/core`.
+   */
+  async fetchLanguages(username, token, maxRepos = DEFAULT_MAX_REPOS) {
+    const repos = await this.getJson(
+      `${GITHUB_API}/users/${encodeURIComponent(username)}/repos?per_page=100&type=owner&sort=pushed`,
+      token
+    );
+    const owned = repos.filter((repo) => !repo.fork).slice(0, maxRepos);
+    const totals = {};
+    for (const repo of owned) {
+      const langs = await this.getJson(
+        `${GITHUB_API}/repos/${encodeURIComponent(username)}/${encodeURIComponent(repo.name)}/languages`,
+        token
+      );
+      for (const [name, bytes] of Object.entries(langs)) {
+        totals[name] = (totals[name] ?? 0) + bytes;
+      }
+    }
+    return totals;
+  }
+  /**
+   * Read the trailing-year contribution calendar. Requires a token (the
+   * calendar is GraphQL-only).
+   */
+  async fetchContributions(username, token) {
+    const query = "query($login:String!){user(login:$login){contributionsCollection{contributionCalendar{totalContributions weeks{contributionDays{date contributionCount}}}}}}";
+    const res = await this.fetchImpl(`${GITHUB_API}/graphql`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+        "user-agent": USER_AGENT
+      },
+      body: JSON.stringify({ query, variables: { login: username } })
+    });
+    if (!res.ok) {
+      throw new GitHubFetchError(`GitHub GraphQL responded ${String(res.status)}.`);
+    }
+    const json = await res.json();
+    if (json.errors && json.errors.length > 0) {
+      throw new GitHubFetchError(`GitHub GraphQL error: ${json.errors[0]?.message ?? "unknown"}.`);
+    }
+    const calendar = json.data?.user?.contributionsCollection?.contributionCalendar;
+    if (!calendar) {
+      throw new GitHubFetchError("GitHub GraphQL response missing the contribution calendar.");
+    }
+    const days = calendar.weeks.flatMap((week) => week.contributionDays).map((day) => ({ date: day.date, count: day.contributionCount }));
+    return { total: calendar.totalContributions, days };
+  }
+  async getJson(url, token) {
+    const headers = {
+      accept: "application/vnd.github+json",
+      "user-agent": USER_AGENT
+    };
+    if (token !== void 0 && token !== "") headers.authorization = `Bearer ${token}`;
+    const res = await this.fetchImpl(url, { headers });
+    if (!res.ok) {
+      throw new GitHubFetchError(`GitHub API responded ${String(res.status)}.`);
+    }
+    return await res.json();
+  }
+};
+
+// src/wakatime.ts
+var WAKATIME_API = "https://wakatime.com/api/v1";
+var DEFAULT_WAKATIME_RANGE = "last_year";
+var WakaTimeFetchError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "WakaTimeFetchError";
+  }
+};
+var WakaTimeClient = class {
+  constructor(fetchImpl = fetch) {
+    this.fetchImpl = fetchImpl;
+  }
+  fetchImpl;
+  /** Total coding seconds for `username` over `range` (default last year). */
+  async fetchCodingSeconds(username, apiKey, range = DEFAULT_WAKATIME_RANGE) {
+    const res = await this.fetchImpl(
+      `${WAKATIME_API}/users/${encodeURIComponent(username)}/stats/${encodeURIComponent(range)}`,
+      // WakaTime Basic auth: the API key is the username, base64-encoded.
+      { headers: { authorization: `Basic ${btoa(apiKey)}` } }
+    );
+    if (!res.ok) {
+      throw new WakaTimeFetchError(`WakaTime API responded ${String(res.status)}.`);
+    }
+    const json = await res.json();
+    const seconds = json.data?.total_seconds;
+    if (typeof seconds !== "number") {
+      throw new WakaTimeFetchError("WakaTime response missing data.total_seconds.");
+    }
+    return seconds;
+  }
+};
+
+// src/fetch-snapshot.ts
+async function fetchActivitySnapshot(config, secrets = {}, deps = {}) {
+  const fetchImpl = deps.fetch ?? fetch;
+  const now = deps.now ?? (() => /* @__PURE__ */ new Date());
+  const onError = deps.onError ?? (() => void 0);
+  const github = new GitHubClient(fetchImpl);
+  const wakatime = new WakaTimeClient(fetchImpl);
+  const snapshot = { lastSyncedAt: now().toISOString() };
+  let contributionsTotal;
+  let codingSeconds;
+  const githubUser = config.github?.username;
+  if (githubUser !== void 0 && githubUser !== "") {
+    if (config.github?.showLanguages !== false) {
+      try {
+        const languages = computeLanguagePercentages(
+          await github.fetchLanguages(githubUser, secrets.githubToken)
+        );
+        if (languages.length > 0) snapshot.languages = languages;
+      } catch (err) {
+        onError("github-languages", err);
+      }
+    }
+    if (config.github?.showContributions !== false && secrets.githubToken) {
+      try {
+        const calendar = await github.fetchContributions(githubUser, secrets.githubToken);
+        snapshot.contributions = calendar;
+        contributionsTotal = calendar.total;
+      } catch (err) {
+        onError("github-contributions", err);
+      }
+    }
+  }
+  const wakatimeUser = config.wakatime?.username;
+  if (wakatimeUser !== void 0 && wakatimeUser !== "" && config.wakatime?.showCodingTime !== false && secrets.wakatimeKey) {
+    try {
+      codingSeconds = await wakatime.fetchCodingSeconds(wakatimeUser, secrets.wakatimeKey);
+      snapshot.codingTime = formatCodingTime(codingSeconds);
+    } catch (err) {
+      onError("wakatime", err);
+    }
+  }
+  if (config.showRank !== false && (contributionsTotal !== void 0 || codingSeconds !== void 0)) {
+    snapshot.rank = deriveRankTier({ contributions: contributionsTotal, codingSeconds });
+  }
+  return snapshot;
+}
+function isEmptySnapshot(snapshot) {
+  return snapshot.languages === void 0 && snapshot.contributions === void 0 && snapshot.codingTime === void 0 && snapshot.rank === void 0;
+}
+export {
+  DEFAULT_MAX_REPOS,
+  DEFAULT_WAKATIME_RANGE,
+  GitHubClient,
+  GitHubFetchError,
+  WakaTimeClient,
+  WakaTimeFetchError,
+  fetchActivitySnapshot,
+  isEmptySnapshot
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fetch-snapshot.ts","../src/github.ts","../src/wakatime.ts"],"sourcesContent":["/**\n * Build an {@link ActivitySnapshot} from the owner's configured sources.\n *\n * Each source is fetched independently and degrades gracefully: a source that\n * is disabled, unconfigured, missing its secret, or failing is simply omitted\n * (its error is reported via {@link ActivityFetchDeps.onError}) rather than\n * aborting the whole snapshot. The caller (a CLI command or scheduled job)\n * decides what to do with a snapshot that gathered nothing — typically keeping\n * the last-known one rather than overwriting it with an empty result.\n *\n * This module performs network I/O, so it lives outside `@takuhon/core` (which\n * is platform-independent); it reuses core's pure transforms to shape the data.\n */\n\nimport {\n  computeLanguagePercentages,\n  deriveRankTier,\n  formatCodingTime,\n  type ActivitySettings,\n  type ActivitySnapshot,\n} from '@takuhon/core';\n\nimport { GitHubClient } from './github.js';\nimport { WakaTimeClient } from './wakatime.js';\n\n/** Secrets for the activity sources. Never persisted; supplied per sync run. */\nexport interface ActivitySecrets {\n  /** GitHub token. Optional for languages; REQUIRED for contributions. */\n  githubToken?: string;\n  /** WakaTime API key. REQUIRED to read coding time. */\n  wakatimeKey?: string;\n}\n\nexport interface ActivityFetchDeps {\n  /** HTTP client. Defaults to the runtime global `fetch` (Node 22+ / Workers). */\n  fetch?: typeof fetch;\n  /** Clock for `lastSyncedAt`; injectable for deterministic tests. */\n  now?: () => Date;\n  /** Reports a per-source failure so the caller can audit-log it. */\n  onError?: (\n    source: 'github-languages' | 'github-contributions' | 'wakatime',\n    err: unknown,\n  ) => void;\n}\n\n/**\n * Fetch and assemble the activity snapshot for the given config. Always\n * resolves (never rejects): failures surface through `onError` and leave the\n * corresponding field absent.\n */\nexport async function fetchActivitySnapshot(\n  config: ActivitySettings,\n  secrets: ActivitySecrets = {},\n  deps: ActivityFetchDeps = {},\n): Promise<ActivitySnapshot> {\n  const fetchImpl = deps.fetch ?? fetch;\n  const now = deps.now ?? ((): Date => new Date());\n  const onError = deps.onError ?? ((): void => undefined);\n  const github = new GitHubClient(fetchImpl);\n  const wakatime = new WakaTimeClient(fetchImpl);\n\n  const snapshot: ActivitySnapshot = { lastSyncedAt: now().toISOString() };\n\n  let contributionsTotal: number | undefined;\n  let codingSeconds: number | undefined;\n\n  const githubUser = config.github?.username;\n  if (githubUser !== undefined && githubUser !== '') {\n    if (config.github?.showLanguages !== false) {\n      try {\n        const languages = computeLanguagePercentages(\n          await github.fetchLanguages(githubUser, secrets.githubToken),\n        );\n        if (languages.length > 0) snapshot.languages = languages;\n      } catch (err) {\n        onError('github-languages', err);\n      }\n    }\n    // Contributions require a token (GraphQL-only); skip silently without one.\n    if (config.github?.showContributions !== false && secrets.githubToken) {\n      try {\n        const calendar = await github.fetchContributions(githubUser, secrets.githubToken);\n        snapshot.contributions = calendar;\n        contributionsTotal = calendar.total;\n      } catch (err) {\n        onError('github-contributions', err);\n      }\n    }\n  }\n\n  const wakatimeUser = config.wakatime?.username;\n  if (\n    wakatimeUser !== undefined &&\n    wakatimeUser !== '' &&\n    config.wakatime?.showCodingTime !== false &&\n    secrets.wakatimeKey\n  ) {\n    try {\n      codingSeconds = await wakatime.fetchCodingSeconds(wakatimeUser, secrets.wakatimeKey);\n      snapshot.codingTime = formatCodingTime(codingSeconds);\n    } catch (err) {\n      onError('wakatime', err);\n    }\n  }\n\n  // Only rank when at least one signal was gathered, so an unconfigured /\n  // failed sync does not stamp a misleading \"D\".\n  if (\n    config.showRank !== false &&\n    (contributionsTotal !== undefined || codingSeconds !== undefined)\n  ) {\n    snapshot.rank = deriveRankTier({ contributions: contributionsTotal, codingSeconds });\n  }\n\n  return snapshot;\n}\n\n/** True when the snapshot carries no metric data (only `lastSyncedAt`). */\nexport function isEmptySnapshot(snapshot: ActivitySnapshot): boolean {\n  return (\n    snapshot.languages === undefined &&\n    snapshot.contributions === undefined &&\n    snapshot.codingTime === undefined &&\n    snapshot.rank === undefined\n  );\n}\n","/**\n * GitHub fetchers for the activity snapshot.\n *\n * Two signals are read:\n * - **Language bytes** via the REST `repos/{owner}/{repo}/languages` endpoint,\n *   aggregated across the user's owned (non-fork) repositories. REST works\n *   unauthenticated (at a low rate limit); a token raises the limit.\n * - **Contribution calendar** via the GraphQL `contributionsCollection`. The\n *   calendar is only exposed over GraphQL (the REST events API does not provide\n *   it), so this REQUIRES a token.\n *\n * The `fetch` implementation is injected so tests can supply fakes; in\n * production it defaults to the runtime global (Node 22+ / Workers).\n */\n\nimport type { ContributionCalendar } from '@takuhon/core';\n\nconst GITHUB_API = 'https://api.github.com';\n\n/** GitHub requires a User-Agent on every request. */\nconst USER_AGENT = 'takuhon-activity';\n\n/** Default cap on repositories scanned for languages, to bound fan-out. */\nexport const DEFAULT_MAX_REPOS = 50;\n\ninterface RepoSummary {\n  name: string;\n  fork: boolean;\n}\n\ninterface GraphQLContributionResponse {\n  data?: {\n    user?: {\n      contributionsCollection?: {\n        contributionCalendar?: {\n          totalContributions: number;\n          weeks: { contributionDays: { date: string; contributionCount: number }[] }[];\n        };\n      };\n    };\n  };\n  errors?: { message: string }[];\n}\n\n/** Thrown when a GitHub request fails; carries no token or host-path detail. */\nexport class GitHubFetchError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options);\n    this.name = 'GitHubFetchError';\n  }\n}\n\nexport class GitHubClient {\n  constructor(private readonly fetchImpl: typeof fetch = fetch) {}\n\n  /**\n   * Aggregate language byte counts across the user's owned, non-fork repos\n   * (capped at `maxRepos`, most-recently-pushed first). Returns raw bytes per\n   * language; the caller converts to percentages via `@takuhon/core`.\n   */\n  async fetchLanguages(\n    username: string,\n    token?: string,\n    maxRepos = DEFAULT_MAX_REPOS,\n  ): Promise<Record<string, number>> {\n    const repos = await this.getJson<RepoSummary[]>(\n      `${GITHUB_API}/users/${encodeURIComponent(username)}/repos?per_page=100&type=owner&sort=pushed`,\n      token,\n    );\n    const owned = repos.filter((repo) => !repo.fork).slice(0, maxRepos);\n\n    const totals: Record<string, number> = {};\n    for (const repo of owned) {\n      const langs = await this.getJson<Record<string, number>>(\n        `${GITHUB_API}/repos/${encodeURIComponent(username)}/${encodeURIComponent(repo.name)}/languages`,\n        token,\n      );\n      for (const [name, bytes] of Object.entries(langs)) {\n        totals[name] = (totals[name] ?? 0) + bytes;\n      }\n    }\n    return totals;\n  }\n\n  /**\n   * Read the trailing-year contribution calendar. Requires a token (the\n   * calendar is GraphQL-only).\n   */\n  async fetchContributions(username: string, token: string): Promise<ContributionCalendar> {\n    const query =\n      'query($login:String!){user(login:$login){contributionsCollection{contributionCalendar{totalContributions weeks{contributionDays{date contributionCount}}}}}}';\n    const res = await this.fetchImpl(`${GITHUB_API}/graphql`, {\n      method: 'POST',\n      headers: {\n        authorization: `Bearer ${token}`,\n        'content-type': 'application/json',\n        'user-agent': USER_AGENT,\n      },\n      body: JSON.stringify({ query, variables: { login: username } }),\n    });\n    if (!res.ok) {\n      throw new GitHubFetchError(`GitHub GraphQL responded ${String(res.status)}.`);\n    }\n    const json = (await res.json()) as GraphQLContributionResponse;\n    if (json.errors && json.errors.length > 0) {\n      throw new GitHubFetchError(`GitHub GraphQL error: ${json.errors[0]?.message ?? 'unknown'}.`);\n    }\n    const calendar = json.data?.user?.contributionsCollection?.contributionCalendar;\n    if (!calendar) {\n      throw new GitHubFetchError('GitHub GraphQL response missing the contribution calendar.');\n    }\n    const days = calendar.weeks\n      .flatMap((week) => week.contributionDays)\n      .map((day) => ({ date: day.date, count: day.contributionCount }));\n    return { total: calendar.totalContributions, days };\n  }\n\n  private async getJson<T>(url: string, token?: string): Promise<T> {\n    const headers: Record<string, string> = {\n      accept: 'application/vnd.github+json',\n      'user-agent': USER_AGENT,\n    };\n    if (token !== undefined && token !== '') headers.authorization = `Bearer ${token}`;\n    const res = await this.fetchImpl(url, { headers });\n    if (!res.ok) {\n      throw new GitHubFetchError(`GitHub API responded ${String(res.status)}.`);\n    }\n    return (await res.json()) as T;\n  }\n}\n","/**\n * WakaTime fetcher for the activity snapshot.\n *\n * Reads total coding seconds over a range from the `users/{user}/stats/{range}`\n * endpoint. WakaTime has no unauthenticated mode, so an API key is REQUIRED; it\n * is sent as HTTP Basic auth (the key base64-encoded) and only ever flows\n * through this sync step — never into any stored document.\n *\n * The `fetch` implementation is injected for tests; production defaults to the\n * runtime global.\n */\n\nconst WAKATIME_API = 'https://wakatime.com/api/v1';\n\n/** Default stats range — recent activity rather than all-time. */\nexport const DEFAULT_WAKATIME_RANGE = 'last_year';\n\ninterface WakaTimeStatsResponse {\n  data?: { total_seconds?: number };\n}\n\n/** Thrown when a WakaTime request fails; carries no key or host-path detail. */\nexport class WakaTimeFetchError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options);\n    this.name = 'WakaTimeFetchError';\n  }\n}\n\nexport class WakaTimeClient {\n  constructor(private readonly fetchImpl: typeof fetch = fetch) {}\n\n  /** Total coding seconds for `username` over `range` (default last year). */\n  async fetchCodingSeconds(\n    username: string,\n    apiKey: string,\n    range = DEFAULT_WAKATIME_RANGE,\n  ): Promise<number> {\n    const res = await this.fetchImpl(\n      `${WAKATIME_API}/users/${encodeURIComponent(username)}/stats/${encodeURIComponent(range)}`,\n      // WakaTime Basic auth: the API key is the username, base64-encoded.\n      { headers: { authorization: `Basic ${btoa(apiKey)}` } },\n    );\n    if (!res.ok) {\n      throw new WakaTimeFetchError(`WakaTime API responded ${String(res.status)}.`);\n    }\n    const json = (await res.json()) as WakaTimeStatsResponse;\n    const seconds = json.data?.total_seconds;\n    if (typeof seconds !== 'number') {\n      throw new WakaTimeFetchError('WakaTime response missing data.total_seconds.');\n    }\n    return seconds;\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@takuhon/activity",
+  "version": "0.12.0",
+  "description": "Developer-activity fetchers (GitHub, WakaTime) that build a takuhon activity snapshot",
+  "license": "Apache-2.0",
+  "author": "Takuhon contributors",
+  "homepage": "https://github.com/takuhon-dev/takuhon/tree/main/packages/activity#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/takuhon-dev/takuhon.git",
+    "directory": "packages/activity"
+  },
+  "bugs": {
+    "url": "https://github.com/takuhon-dev/takuhon/issues"
+  },
+  "keywords": [
+    "takuhon",
+    "profile",
+    "github",
+    "wakatime",
+    "activity"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@takuhon/core": "0.12.0"
+  },
+  "scripts": {
+    "typecheck": "tsc",
+    "build": "tsup src/index.ts --format esm --dts --clean --sourcemap",
+    "test": "vitest run"
+  }
+}