@finopsbricks/fob-snap 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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 FinOpsBricks
+
+   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/README.md

@@ -0,0 +1,70 @@
+# fob-snap
+
+CLI + importable client for [Snapshots](https://snapshots.finopsbricks.com) — push versioned
+snapshots and manage widgets/dashboards from the terminal or a script.
+
+Snapshots is push-first: you POST a full, typed payload to a widget and it's stored as a new
+immutable version. `fob-snap` makes that the one-liner it should be.
+
+## Install
+
+```bash
+npm install -g @finopsbricks/fob-snap
+```
+
+## Quick start
+
+```bash
+# 1. Save credentials (prompts for the secret if you omit --api-secret)
+fob-snap config profiles add default --api-key fob_app_xxx
+
+# 2. Create a widget
+fob-snap widgets create --title "MRR" --type kpi
+
+# 3. Push a snapshot — the whole point
+fob-snap snapshots push <widget-id> --data '{"value":145000,"label":"MRR","unit":"$"}'
+fob-snap snapshots push <widget-id> --data @payload.json --as-of 2026-01-31T00:00:00Z
+
+# 4. Scrub the history
+fob-snap snapshots list <widget-id>
+```
+
+Use a **Push Only** API key for push scripts. `--as-of` is the business time the data describes
+(defaults to now); every push is a new version, never an overwrite.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `config profiles add\|list\|use\|remove\|current` | Manage credential profiles (`~/.fob/fob-snap/config.yml`) |
+| `snapshots push <widget> --data <json>` | Push a snapshot (full typed payload) |
+| `snapshots list <widget>` | List a widget's versions, newest first |
+| `widgets list\|show\|create\|delete` | Manage widgets |
+| `dashboards list\|show\|create\|delete` | Manage dashboards |
+| `dashboards add-widget\|remove-widget <dashboard> …` | Place / unplace widgets |
+| `dashboards share\|unshare <dashboard>` | Create / revoke the public link |
+
+`--profile <name>` selects a profile per-command; `--json` prints raw JSON on any read command.
+`FOB_DEBUG=1` prints stack traces.
+
+## As a library
+
+The same client the CLI uses is importable — inject credentials, never read from env:
+
+```js
+import { fobSnap } from '@finopsbricks/fob-snap';
+
+const snap = fobSnap({ api_key, api_secret }); // api_url optional (hosted origin)
+await snap.snapshots.push(widgetId, { data: { value: 145000 }, as_of: '2026-01-31T00:00:00Z' });
+const { data: widgets } = await snap.widgets.list();
+```
+
+## Auth
+
+Requests send `api-key` / `api-secret` headers. Create a key in the Snapshots app under
+**Settings → API keys**; the **Push Only** preset grants exactly `snapshot:create` (+ read).
+Widget/dashboard management needs a key with the matching `widget:*` / `dashboard:*` scopes.
+
+## License
+
+Apache-2.0

package/bin/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../src/cli/index.js';
+
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@finopsbricks/fob-snap",
+  "version": "0.1.0",
+  "description": "Snapshots app client + fob-snap CLI (2-in-1). Import the client in workers, or use the CLI to push snapshots and manage widgets/dashboards.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "fob-snap": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest",
+    "typecheck": "tsc -p jsconfig.json"
+  },
+  "keywords": [
+    "snapshots",
+    "dashboards",
+    "push-metrics",
+    "api-client",
+    "cli",
+    "finops",
+    "finopsbricks"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/finopsbricks/fob-snap.git"
+  },
+  "homepage": "https://github.com/finopsbricks/fob-snap#readme",
+  "bugs": "https://github.com/finopsbricks/fob-snap/issues",
+  "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
+    "commander": "^15.0.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@types/node": "^22.20.1",
+    "jest": "^29.7.0",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli/_helpers.js

@@ -0,0 +1,62 @@
+/**
+ * Shared CLI helpers: the `safe` handler adapter, `clientFor` (builds the authed
+ * client from the resolved profile), and small option builders.
+ */
+
+import { resolveCredentials } from './config-store.js';
+import { fobSnap } from '../index.js';
+
+/**
+ * Adapt a handler taking one merged `argv` to commander's `(…positionals, opts, cmd)`
+ * signature, with clean-exit behaviour on an unexpected throw (`FOB_DEBUG=1` for the stack).
+ * Positional names come from the command's declaration, camelised like option names.
+ */
+export function safe(handler) {
+  return async (...args) => {
+    const cmd = args[args.length - 1];
+    const opts = args[args.length - 2];
+    const positionals = args.slice(0, -2);
+
+    const argv = { ...opts };
+    const declared = cmd.registeredArguments ?? [];
+    declared.forEach((arg, i) => {
+      argv[toCamel(arg.name())] = positionals[i];
+    });
+    // Global options live on the root command — merge them down (leaf wins).
+    let parent = cmd.parent;
+    while (parent) {
+      Object.assign(argv, parent.opts(), argv);
+      parent = parent.parent;
+    }
+
+    try {
+      await handler(argv);
+    } catch (err) {
+      console.error(`Error: ${err.message}`);
+      if (err.details?.length) for (const d of err.details) console.error(`  - ${d}`);
+      if (process.env.FOB_DEBUG) console.error(err.stack);
+      process.exit(1);
+    }
+  };
+}
+
+function toCamel(s) {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** Build the authed Snapshots client from the current profile. */
+export function clientFor() {
+  return fobSnap(resolveCredentials());
+}
+
+/** Standard `--json` output flag. */
+export function jsonOption(cmd) {
+  return cmd.option('--json', 'Output raw JSON');
+}
+
+/** Pagination + `--json` for list commands. */
+export function listOptions(cmd) {
+  return jsonOption(cmd)
+    .option('--page <n>', 'Page number', Number, 1)
+    .option('--limit <n>', 'Page size (max 500)', Number, 100);
+}

package/src/cli/_output.js

@@ -0,0 +1,31 @@
+/** Plain-text table + JSON output helpers for CLI commands. */
+
+/** Pretty-print a value as indented JSON. */
+export function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+/**
+ * Render rows as an aligned text table.
+ * @param {Array<{ header: string, get: (row: any) => string }>} columns
+ * @param {any[]} rows
+ */
+export function printTable(columns, rows) {
+  if (!rows || rows.length === 0) {
+    console.log('(none)');
+    return;
+  }
+  const cells = rows.map((row) => columns.map((c) => String(c.get(row) ?? '')));
+  const widths = columns.map((c, i) => Math.max(c.header.length, ...cells.map((r) => r[i].length)));
+  const line = (arr) => arr.map((v, i) => v.padEnd(widths[i])).join('  ').trimEnd();
+
+  console.log(line(columns.map((c) => c.header)));
+  console.log(line(widths.map((w) => '-'.repeat(w))));
+  for (const r of cells) console.log(line(r));
+}
+
+/** Truncate a string for table display. */
+export function trunc(v, n = 32) {
+  const s = v == null ? '' : String(v);
+  return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}

package/src/cli/config/index.js

@@ -0,0 +1,83 @@
+/**
+ * `fob-snap config profiles <action>` — manage credential profiles.
+ *
+ * A profile is a named `{ api_url, api_key, api_secret }` set stored in
+ * ~/.fob/fob-snap/config.yml. `add` takes flags, or prompts interactively for any
+ * missing credential (secret via a hidden prompt) — the `login` flow.
+ */
+
+import { Command } from 'commander';
+import { input, password } from '@inquirer/prompts';
+
+import { safe, jsonOption } from '../_helpers.js';
+import { printJson, printTable } from '../_output.js';
+import { DEFAULT_API_URL } from '../../http.js';
+import {
+  addProfile, removeProfile, useProfile, listProfiles, describeCurrent,
+} from '../config-store.js';
+
+async function addHandler(argv) {
+  const api_url = argv.apiUrl || DEFAULT_API_URL;
+  const api_key = argv.apiKey || (await input({ message: 'API key:' }));
+  const api_secret = argv.apiSecret || (await password({ message: 'API secret:', mask: '*' }));
+  if (!api_key || !api_secret) throw new Error('Both an API key and secret are required.');
+
+  addProfile(argv.name, { api_url, api_key, api_secret });
+  console.log(`Saved Snapshots credentials for profile '${argv.name}' (${api_url}).`);
+}
+
+function listHandler(argv) {
+  const { current, path, profiles } = listProfiles();
+  if (argv.json) return printJson({ current, profiles });
+  printTable(
+    [
+      { header: '', get: (p) => (p.current ? '*' : ' ') },
+      { header: 'PROFILE', get: (p) => p.name },
+      { header: 'API URL', get: (p) => p.api_url },
+    ],
+    profiles,
+  );
+  console.log(`\nConfig: ${path}`);
+}
+
+function useHandler(argv) {
+  useProfile(argv.name);
+  console.log(`Now using profile '${argv.name}'.`);
+}
+
+function removeHandler(argv) {
+  removeProfile(argv.name);
+  console.log(`Removed profile '${argv.name}'.`);
+}
+
+function currentHandler(argv) {
+  const cur = describeCurrent();
+  if (!cur) throw new Error('No profile selected. Run `fob-snap config profiles add <name>`.');
+  if (argv.json) return printJson(cur);
+  console.log(`Profile '${cur.name}' → ${cur.api_url}`);
+}
+
+function buildProfilesCommand() {
+  const profiles = new Command('profiles').alias('login').description('Manage credential profiles');
+
+  profiles
+    .command('add')
+    .description("Add or update a profile's credentials (prompts for any omitted secret)")
+    .argument('<name>', 'Profile name')
+    .option('--api-url <url>', `API base URL (origin only). Defaults to ${DEFAULT_API_URL}`, DEFAULT_API_URL)
+    .option('--api-key <key>', 'API key')
+    .option('--api-secret <secret>', 'API secret')
+    .action(safe(addHandler));
+
+  jsonOption(profiles.command('list').description('List profiles (current marked *)')).action(safe(listHandler));
+  jsonOption(profiles.command('current').alias('whoami').description('Show the active profile')).action(safe(currentHandler));
+
+  profiles.command('use').description('Set the current profile').argument('<name>', 'Profile name').action(safe(useHandler));
+  profiles.command('remove').alias('rm').description('Remove a profile').argument('<name>', 'Profile name').action(safe(removeHandler));
+
+  return profiles;
+}
+
+export function buildConfigCommand() {
+  return new Command('config').description('Manage credential profiles').addCommand(buildProfilesCommand());
+}

package/src/cli/config-store.js

@@ -0,0 +1,109 @@
+/**
+ * CLI credential store — reads/writes ~/.fob/fob-snap/config.yml (mode 0600) and
+ * resolves which credentials the current command uses.
+ *
+ * Config lives under the shared family root ~/.fob/ so every fob-<tool> keeps its
+ * config in one place. Override the whole dir with FOB_SNAP_CONFIG_DIR.
+ *
+ * CLI-only: the importable client (src/index.js) never imports this. Handlers call
+ * resolveCredentials() and pass the result to client functions.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+
+const CONFIG_DIR = process.env.FOB_SNAP_CONFIG_DIR || join(homedir(), '.fob', 'fob-snap');
+const CONFIG_PATH = join(CONFIG_DIR, 'config.yml');
+
+let profileOverride = null;
+
+/** Set by the `--profile <name>` global flag (root preAction hook). Beats current_profile. */
+export function setProfileOverride(name) {
+  profileOverride = name;
+}
+
+export function loadConfig() {
+  if (existsSync(CONFIG_PATH)) {
+    const cfg = yaml.load(readFileSync(CONFIG_PATH, 'utf8')) || {};
+    return { current_profile: cfg.current_profile ?? null, profiles: cfg.profiles ?? {} };
+  }
+  return { current_profile: null, profiles: {} };
+}
+
+export function saveConfig(cfg) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, yaml.dump(cfg), { mode: 0o600 });
+}
+
+export function addProfile(name, { api_url, api_key, api_secret }) {
+  const cfg = loadConfig();
+  cfg.profiles[name] = { api_url, api_key, api_secret };
+  if (!cfg.current_profile) cfg.current_profile = name;
+  saveConfig(cfg);
+  return cfg;
+}
+
+export function removeProfile(name) {
+  const cfg = loadConfig();
+  if (!cfg.profiles[name]) throw new Error(`No profile named '${name}'.`);
+  delete cfg.profiles[name];
+  if (cfg.current_profile === name) cfg.current_profile = Object.keys(cfg.profiles)[0] ?? null;
+  saveConfig(cfg);
+  return cfg;
+}
+
+export function useProfile(name) {
+  const cfg = loadConfig();
+  if (!cfg.profiles[name]) throw new Error(`No profile named '${name}'. Run \`fob-snap config profiles add ${name}\`.`);
+  cfg.current_profile = name;
+  saveConfig(cfg);
+  return cfg;
+}
+
+export function configPath() {
+  return CONFIG_PATH;
+}
+
+/** Profiles for display — non-secret metadata only (name, current, api_url). */
+export function listProfiles() {
+  const cfg = loadConfig();
+  const profiles = Object.entries(cfg.profiles).map(([name, p]) => ({
+    name,
+    current: name === cfg.current_profile,
+    api_url: p.api_url,
+  }));
+  return { current: cfg.current_profile, path: CONFIG_PATH, profiles };
+}
+
+/**
+ * Resolve credentials for the current command.
+ * Precedence: `--profile` override > config `current_profile`. Does not read env —
+ * an env var that silently overrode the active profile would be a footgun.
+ * @returns {{ api_url: string, api_key: string, api_secret: string, name: string }}
+ */
+export function resolveCredentials() {
+  const cfg = loadConfig();
+  const name = profileOverride || cfg.current_profile;
+
+  if (profileOverride && !cfg.profiles[profileOverride]) {
+    throw new Error(`Profile '${profileOverride}' is not configured. Run \`fob-snap config profiles add ${profileOverride}\`.`);
+  }
+  if (name && cfg.profiles[name]) {
+    return { ...cfg.profiles[name], name };
+  }
+  throw new Error(
+    'No Snapshots profile selected. Run `fob-snap config profiles add <name>`, then `use <name>` (or pass --profile <name>).',
+  );
+}
+
+/** Non-secret description of the identity the CLI would use right now, or null. */
+export function describeCurrent() {
+  try {
+    const { api_key, api_secret, ...rest } = resolveCredentials();
+    return rest;
+  } catch {
+    return null;
+  }
+}

package/src/cli/dashboards/index.js

@@ -0,0 +1,98 @@
+/**
+ * `fob-snap dashboards <action>` — manage dashboards, placements, and share links.
+ */
+
+import { Command } from 'commander';
+
+import { safe, listOptions, jsonOption, clientFor } from '../_helpers.js';
+import { printJson, printTable, trunc } from '../_output.js';
+
+async function listHandler(argv) {
+  const res = await clientFor().dashboards.list({ page: argv.page, limit: argv.limit });
+  if (argv.json) return printJson(res);
+  printTable(
+    [
+      { header: 'ID', get: (d) => d.id },
+      { header: 'TITLE', get: (d) => trunc(d.title, 40) },
+      { header: 'CREATED', get: (d) => d.created_at },
+    ],
+    res.data,
+  );
+  if (res.page_context) console.log(`\n${res.page_context.total} dashboard(s).`);
+}
+
+async function showHandler(argv) {
+  const client = clientFor();
+  const { data: dashboard } = await client.dashboards.get(argv.id);
+  const { data: placements } = await client.dashboards.listWidgets(argv.id);
+  printJson({ ...dashboard, widgets: placements });
+}
+
+async function createHandler(argv) {
+  const { data: dashboard } = await clientFor().dashboards.create({ title: argv.title });
+  if (argv.json) return printJson(dashboard);
+  console.log(`Created dashboard '${dashboard.title}' → ${dashboard.id}`);
+}
+
+async function deleteHandler(argv) {
+  await clientFor().dashboards.delete(argv.id);
+  console.log(`Deleted dashboard ${argv.id}.`);
+}
+
+async function addWidgetHandler(argv) {
+  const { data: placement } = await clientFor().dashboards.addWidget(argv.dashboard, { widget_id: argv.widget });
+  if (argv.json) return printJson(placement);
+  console.log(`Placed widget ${argv.widget} on dashboard ${argv.dashboard} (placement ${placement.id}).`);
+}
+
+async function removeWidgetHandler(argv) {
+  await clientFor().dashboards.removeWidget(argv.dashboard, argv.placement);
+  console.log(`Removed placement ${argv.placement} from dashboard ${argv.dashboard}.`);
+}
+
+async function shareHandler(argv) {
+  const { data: share } = await clientFor().dashboards.share(argv.id);
+  if (argv.json) return printJson(share);
+  console.log(`Public link: /s/${share.share_token}`);
+}
+
+async function unshareHandler(argv) {
+  await clientFor().dashboards.unshare(argv.id);
+  console.log(`Revoked the public link for dashboard ${argv.id}.`);
+}
+
+export function buildDashboardsCommand() {
+  const dashboards = new Command('dashboards').alias('dashboard').description('Manage dashboards, placements, and share links');
+
+  listOptions(dashboards.command('list').description("List the org's dashboards")).action(safe(listHandler));
+  jsonOption(dashboards.command('show').description('Show a dashboard with its placements').argument('<id>', 'Dashboard id')).action(safe(showHandler));
+
+  dashboards
+    .command('create')
+    .description('Create a dashboard')
+    .requiredOption('--title <title>', 'Dashboard title')
+    .option('--json', 'Output raw JSON')
+    .action(safe(createHandler));
+
+  dashboards.command('delete').alias('rm').description('Delete a dashboard').argument('<id>', 'Dashboard id').action(safe(deleteHandler));
+
+  dashboards
+    .command('add-widget')
+    .description('Place a widget on a dashboard')
+    .argument('<dashboard>', 'Dashboard id')
+    .argument('<widget>', 'Widget id')
+    .option('--json', 'Output raw JSON')
+    .action(safe(addWidgetHandler));
+
+  dashboards
+    .command('remove-widget')
+    .description('Remove a placement from a dashboard')
+    .argument('<dashboard>', 'Dashboard id')
+    .argument('<placement>', 'Placement id (from `dashboards show`)')
+    .action(safe(removeWidgetHandler));
+
+  jsonOption(dashboards.command('share').description('Create/return the public share link').argument('<id>', 'Dashboard id')).action(safe(shareHandler));
+  dashboards.command('unshare').description('Revoke the public share link').argument('<id>', 'Dashboard id').action(safe(unshareHandler));
+
+  return dashboards;
+}

package/src/cli/getting-started.js

@@ -0,0 +1,26 @@
+import { describeCurrent } from './config-store.js';
+import { DEFAULT_API_URL } from '../http.js';
+
+export function gettingStartedHandler() {
+  const current = describeCurrent();
+  if (current) {
+    console.log(`You're set up — using profile '${current.name}' (${current.api_url}).\n`);
+  }
+  console.log(`fob-snap — push snapshots and manage widgets/dashboards from the terminal.
+
+1. Add a profile (prompts for the secret):
+     fob-snap config profiles add default --api-key <KEY>
+   (api_url defaults to ${DEFAULT_API_URL}; use --api-url for self-hosted/staging.)
+
+2. Create a widget:
+     fob-snap widgets create --title "MRR" --type kpi
+
+3. Push a snapshot (the whole point):
+     fob-snap snapshots push <widget-id> --data '{"value":145000,"label":"MRR","unit":"$"}'
+     fob-snap snapshots push <widget-id> --data @payload.json --as-of 2026-01-31T00:00:00Z
+
+4. Scrub the history:
+     fob-snap snapshots list <widget-id>
+
+Every push is a new immutable version. Use a Push Only API key for push scripts.`);
+}

package/src/cli/index.js

@@ -0,0 +1,55 @@
+/**
+ * CLI entry point — a three-level command tree:
+ *
+ *   fob-snap <resource> <action> [target] [options]
+ *
+ * Credentials come from ~/.fob/fob-snap/config.yml; `config` manages profiles.
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+import { Command } from 'commander';
+
+import { setProfileOverride } from './config-store.js';
+import { gettingStartedHandler } from './getting-started.js';
+import { buildConfigCommand } from './config/index.js';
+import { buildSnapshotsCommand } from './snapshots/index.js';
+import { buildWidgetsCommand } from './widgets/index.js';
+import { buildDashboardsCommand } from './dashboards/index.js';
+
+function packageVersion() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return JSON.parse(readFileSync(join(here, '..', '..', 'package.json'), 'utf8')).version;
+}
+
+export function run(argv) {
+  const program = new Command();
+
+  program
+    .name('fob-snap')
+    .usage('<resource> <action> [target] [options]')
+    .description('Push snapshots and manage widgets/dashboards for Snapshots (snapshots.finopsbricks.com).')
+    .version(packageVersion(), '-v, --version', 'Show version number')
+    .option('--profile <name>', 'Use credentials from a specific configured profile')
+    .hook('preAction', (thisCommand) => {
+      const { profile } = thisCommand.opts();
+      if (profile) setProfileOverride(profile);
+    });
+
+  program
+    .command('getting-started')
+    .description('Print setup instructions')
+    .action(gettingStartedHandler);
+
+  program
+    .addCommand(buildConfigCommand())
+    .addCommand(buildSnapshotsCommand())
+    .addCommand(buildWidgetsCommand())
+    .addCommand(buildDashboardsCommand())
+    .allowUnknownOption(false)
+    .showHelpAfterError();
+
+  program.parse(argv, { from: 'user' });
+}

package/src/cli/snapshots/index.js

@@ -0,0 +1,71 @@
+/**
+ * `fob-snap snapshots <action>` — push and list snapshot versions.
+ *
+ * `push` is the product's defining action: submit a FULL typed payload and it's
+ * stored as a new immutable version.
+ */
+
+import { readFileSync } from 'node:fs';
+import { Command } from 'commander';
+
+import { safe, listOptions, clientFor } from '../_helpers.js';
+import { printJson, printTable, trunc } from '../_output.js';
+
+/**
+ * Parse a `--data` argument: `@path` reads a JSON file, otherwise the value is
+ * treated as an inline JSON string. Returns the parsed `data` payload.
+ */
+function parseData(arg) {
+  if (!arg) throw new Error('Provide the payload with --data <@file.json | inline-json>.');
+  const raw = arg.startsWith('@') ? readFileSync(arg.slice(1), 'utf8') : arg;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`--data is not valid JSON: ${err.message}`);
+  }
+  // Accept either the bare payload, or a full { data, as_of } envelope.
+  return parsed && typeof parsed === 'object' && 'data' in parsed ? parsed : { data: parsed };
+}
+
+async function pushHandler(argv) {
+  const envelope = parseData(argv.data);
+  const body = { data: envelope.data, as_of: argv.asOf ?? envelope.as_of };
+  const { data: snapshot } = await clientFor().snapshots.push(argv.widget, body);
+  if (argv.json) return printJson(snapshot);
+  console.log(`Pushed v${snapshot.version} to ${snapshot.widget} (as of ${snapshot.as_of}).`);
+}
+
+async function listHandler(argv) {
+  const res = await clientFor().snapshots.list(argv.widget, { page: argv.page, limit: argv.limit });
+  if (argv.json) return printJson(res);
+  printTable(
+    [
+      { header: 'VERSION', get: (s) => `v${s.version}` },
+      { header: 'AS OF', get: (s) => s.as_of },
+      { header: 'RECEIVED', get: (s) => s.received_at },
+      { header: 'DATA', get: (s) => trunc(JSON.stringify(s.data), 40) },
+    ],
+    res.data,
+  );
+  if (res.page_context) console.log(`\n${res.page_context.total} version(s).`);
+}
+
+export function buildSnapshotsCommand() {
+  const snapshots = new Command('snapshots').alias('snap').description('Push and list snapshot versions');
+
+  snapshots
+    .command('push')
+    .description('Push a snapshot (full typed payload) to a widget')
+    .argument('<widget>', 'Widget id')
+    .requiredOption('--data <json>', 'Payload as inline JSON or @file.json (bare payload, or { data, as_of })')
+    .option('--as-of <iso>', 'Business time this data describes (ISO 8601; defaults to now)')
+    .option('--json', 'Output raw JSON')
+    .action(safe(pushHandler));
+
+  listOptions(
+    snapshots.command('list').description("List a widget's versions, newest first").argument('<widget>', 'Widget id'),
+  ).action(safe(listHandler));
+
+  return snapshots;
+}

package/src/cli/widgets/index.js

@@ -0,0 +1,83 @@
+/**
+ * `fob-snap widgets <action>` — manage widgets over the REST API.
+ */
+
+import { readFileSync } from 'node:fs';
+import { Command } from 'commander';
+
+import { safe, listOptions, jsonOption, clientFor } from '../_helpers.js';
+import { printJson, printTable, trunc } from '../_output.js';
+
+const WIDGET_TYPES = ['line', 'bar', 'area', 'kpi', 'table', 'pie'];
+
+function parseConfig(arg) {
+  if (!arg) return undefined;
+  const raw = arg.startsWith('@') ? readFileSync(arg.slice(1), 'utf8') : arg;
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`--config is not valid JSON: ${err.message}`);
+  }
+}
+
+async function listHandler(argv) {
+  const res = await clientFor().widgets.list({ page: argv.page, limit: argv.limit });
+  if (argv.json) return printJson(res);
+  printTable(
+    [
+      { header: 'ID', get: (w) => w.id },
+      { header: 'TITLE', get: (w) => trunc(w.title, 32) },
+      { header: 'TYPE', get: (w) => w.type },
+      { header: 'RETENTION', get: (w) => (w.retention_days == null ? 'keep-all' : `${w.retention_days}d`) },
+      { header: 'CREATED', get: (w) => w.created_at },
+    ],
+    res.data,
+  );
+  if (res.page_context) console.log(`\n${res.page_context.total} widget(s).`);
+}
+
+async function showHandler(argv) {
+  const { data: widget } = await clientFor().widgets.get(argv.id);
+  printJson(widget);
+}
+
+async function createHandler(argv) {
+  if (!WIDGET_TYPES.includes(argv.type)) {
+    throw new Error(`--type must be one of: ${WIDGET_TYPES.join(', ')}`);
+  }
+  const body = {
+    title: argv.title,
+    type: argv.type,
+    retention_days: argv.retentionDays === undefined ? null : Number(argv.retentionDays),
+    config: parseConfig(argv.config),
+  };
+  const { data: widget } = await clientFor().widgets.create(body);
+  if (argv.json) return printJson(widget);
+  console.log(`Created ${argv.type} widget '${widget.title}' → ${widget.id}`);
+}
+
+async function deleteHandler(argv) {
+  await clientFor().widgets.delete(argv.id);
+  console.log(`Deleted widget ${argv.id}.`);
+}
+
+export function buildWidgetsCommand() {
+  const widgets = new Command('widgets').alias('widget').description('Manage widgets');
+
+  listOptions(widgets.command('list').description("List the org's widgets")).action(safe(listHandler));
+  jsonOption(widgets.command('show').description('Show one widget').argument('<id>', 'Widget id')).action(safe(showHandler));
+
+  widgets
+    .command('create')
+    .description('Create a widget')
+    .requiredOption('--title <title>', 'Widget title')
+    .requiredOption('--type <type>', `Widget type (${WIDGET_TYPES.join('|')})`)
+    .option('--retention-days <n>', 'Keep only the last N days of versions (default: keep all)')
+    .option('--config <json>', 'Visualization config as inline JSON or @file.json')
+    .option('--json', 'Output raw JSON')
+    .action(safe(createHandler));
+
+  widgets.command('delete').alias('rm').description('Delete a widget (snapshots cascade)').argument('<id>', 'Widget id').action(safe(deleteHandler));
+
+  return widgets;
+}

package/src/http.js

@@ -0,0 +1,130 @@
+// @ts-check
+/**
+ * Snapshots API transport.
+ *
+ * PURE: credentials come from the `credentials` argument only — this module never
+ * reads `process.env` or the CLI config file. The CLI resolves creds from its config
+ * profiles and injects them; workers inject their own. (engineering-standards
+ * `no-ambient-configuration`.)
+ *
+ * Base URL is origin-only (e.g. https://snapshots.finopsbricks.com); the `/api/v1`
+ * prefix is carried in the paths passed by the resource layer.
+ */
+
+/**
+ * @typedef {Object} Credentials
+ * @property {string} api_key
+ * @property {string} api_secret
+ * @property {string} [api_url] - origin only; defaults to the hosted endpoint
+ */
+
+/** Origin the client talks to when the caller doesn't supply `api_url`. */
+export const DEFAULT_API_URL = 'https://snapshots.finopsbricks.com';
+
+export class ApiError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, status?: number, details?: string[]|null }} [opts]
+   */
+  constructor(message, { code, status, details } = {}) {
+    super(message);
+    this.name = 'ApiError';
+    this.code = code;
+    this.status = status;
+    this.details = details || null;
+  }
+}
+
+/**
+ * @param {Credentials} credentials
+ * @returns {{ api_url: string, api_key: string, api_secret: string }}
+ */
+function resolveCreds(credentials) {
+  const api_url = credentials?.api_url ?? DEFAULT_API_URL;
+  const api_key = credentials?.api_key;
+  const api_secret = credentials?.api_secret;
+  if (!api_key || !api_secret) {
+    throw new ApiError(
+      `Missing Snapshots credentials: pass { api_key, api_secret } (api_url optional, defaults to ${DEFAULT_API_URL}).`,
+      { code: 'NO_CREDENTIALS' },
+    );
+  }
+  return { api_url, api_key, api_secret };
+}
+
+function buildUrl(baseUrl, path, searchParams) {
+  const base = baseUrl.endsWith('/') ? baseUrl : baseUrl + '/';
+  const url = new URL(path.replace(/^\//, ''), base);
+  if (searchParams) {
+    for (const [key, value] of Object.entries(searchParams)) {
+      if (value !== undefined && value !== null && value !== '') {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  return url;
+}
+
+/**
+ * @param {string} method
+ * @param {string} path
+ * @param {any} [body]
+ * @param {{ credentials: Credentials, searchParams?: Object }} options
+ */
+async function apiRequest(method, path, body, { credentials, searchParams } = /** @type {any} */ ({})) {
+  const creds = resolveCreds(credentials);
+  const url = buildUrl(creds.api_url, path, searchParams);
+
+  const headers = {
+    'api-key': creds.api_key,
+    'api-secret': creds.api_secret,
+    accept: 'application/json',
+  };
+  const init = { method, headers };
+  if (body !== undefined) {
+    headers['content-type'] = 'application/json';
+    init.body = JSON.stringify(body);
+  }
+
+  let response;
+  try {
+    response = await fetch(url, init);
+  } catch (err) {
+    throw new ApiError(`Network error reaching ${url.origin}: ${err.message}`, { code: 'NETWORK_ERROR' });
+  }
+
+  const text = await response.text();
+  let respBody = null;
+  if (text) {
+    try {
+      respBody = JSON.parse(text);
+    } catch {
+      throw new ApiError(
+        `Invalid JSON response (status ${response.status}): ${text.slice(0, 200)}`,
+        { code: 'INVALID_RESPONSE', status: response.status },
+      );
+    }
+  }
+
+  if (!response.ok) {
+    const code = respBody?.error?.code || 'HTTP_ERROR';
+    const message = respBody?.error?.message || `${response.status} ${response.statusText}`;
+    throw new ApiError(message, { code, status: response.status, details: respBody?.error?.details || null });
+  }
+
+  return respBody;
+}
+
+/**
+ * Bind credentials once and expose verb helpers. The resource layer builds on this,
+ * so every endpoint is defined once and the CLI and importable client can't drift.
+ * @param {Credentials} credentials
+ */
+export function createTransport(credentials) {
+  return {
+    get: (path, opts = {}) => apiRequest('GET', path, undefined, { credentials, ...opts }),
+    post: (path, body, opts = {}) => apiRequest('POST', path, body ?? {}, { credentials, ...opts }),
+    patch: (path, body, opts = {}) => apiRequest('PATCH', path, body ?? {}, { credentials, ...opts }),
+    delete: (path, opts = {}) => apiRequest('DELETE', path, undefined, { credentials, ...opts }),
+  };
+}

package/src/index.js

@@ -0,0 +1,33 @@
+// @ts-check
+/**
+ * @fob/snap — the importable Snapshots client.
+ *
+ *   import { fobSnap } from '@finopsbricks/fob-snap';
+ *   const snap = fobSnap({ api_key, api_secret });   // api_url optional (hosted origin)
+ *   await snap.snapshots.push(widgetId, { data, as_of });
+ *   const { data } = await snap.widgets.list();
+ *
+ * The `fob-snap` CLI builds the same client (see src/cli/_helpers.js `clientFor`) and
+ * calls these same namespaces, so the CLI and library can never drift: every endpoint
+ * is defined once, in src/resources/.
+ */
+
+import { createTransport } from './http.js';
+import { buildSnapshots } from './resources/snapshots.js';
+import { buildWidgets } from './resources/widgets.js';
+import { buildDashboards } from './resources/dashboards.js';
+
+/**
+ * @param {import('./http.js').Credentials} credentials Required `{ api_key, api_secret }`;
+ *   optional `api_url` (origin-only) overrides the hosted endpoint. Never read from env.
+ */
+export function fobSnap(credentials) {
+  const ctx = createTransport(credentials);
+  return {
+    snapshots: buildSnapshots(ctx),
+    widgets: buildWidgets(ctx),
+    dashboards: buildDashboards(ctx),
+  };
+}
+
+export { ApiError, createTransport, DEFAULT_API_URL } from './http.js';

package/src/resources/dashboards.js

@@ -0,0 +1,36 @@
+// @ts-check
+/** Dashboards resource — CRUD + placements + share over /api/v1/dashboards. */
+
+export function buildDashboards(ctx) {
+  return {
+    /** @param {{ page?: number, limit?: number }} [params] */
+    list: ({ page, limit } = {}) => ctx.get('/api/v1/dashboards', { searchParams: { page, limit } }),
+
+    /** @param {string} id */
+    get: (id) => ctx.get(`/api/v1/dashboards/${id}`),
+
+    /** @param {{ title: string }} body */
+    create: (body) => ctx.post('/api/v1/dashboards', body),
+
+    /** @param {string} id @param {{ title?: string, layout?: Object }} patch */
+    update: (id, patch) => ctx.patch(`/api/v1/dashboards/${id}`, patch),
+
+    /** @param {string} id */
+    delete: (id) => ctx.delete(`/api/v1/dashboards/${id}`),
+
+    /** List placements on a dashboard. @param {string} id */
+    listWidgets: (id) => ctx.get(`/api/v1/dashboards/${id}/widgets`),
+
+    /** Place a widget. @param {string} id @param {{ widget_id: string, position?: Object }} body */
+    addWidget: (id, body) => ctx.post(`/api/v1/dashboards/${id}/widgets`, body),
+
+    /** Remove a placement. @param {string} id @param {string} placementId */
+    removeWidget: (id, placementId) => ctx.delete(`/api/v1/dashboards/${id}/widgets/${placementId}`),
+
+    /** Create/return the public share link. @param {string} id */
+    share: (id) => ctx.post(`/api/v1/dashboards/${id}/share`, {}),
+
+    /** Revoke the public share link. @param {string} id */
+    unshare: (id) => ctx.delete(`/api/v1/dashboards/${id}/share`),
+  };
+}

package/src/resources/snapshots.js

@@ -0,0 +1,27 @@
+// @ts-check
+/**
+ * Snapshots resource — the product's defining endpoint (push, not pull).
+ * A push submits a FULL typed payload; it's stored as a new immutable version.
+ */
+
+/** @typedef {import('../http.js').createTransport} Transport */
+
+export function buildSnapshots(ctx) {
+  return {
+    /**
+     * Push a snapshot to a widget.
+     * @param {string} widgetId
+     * @param {{ data: Object, as_of?: string }} body
+     */
+    push: (widgetId, { data, as_of } = /** @type {any} */ ({})) =>
+      ctx.post(`/api/v1/widgets/${widgetId}/snapshots`, { data, as_of }),
+
+    /**
+     * List a widget's snapshot versions, newest first.
+     * @param {string} widgetId
+     * @param {{ page?: number, limit?: number }} [params]
+     */
+    list: (widgetId, { page, limit } = {}) =>
+      ctx.get(`/api/v1/widgets/${widgetId}/snapshots`, { searchParams: { page, limit } }),
+  };
+}

package/src/resources/widgets.js

@@ -0,0 +1,21 @@
+// @ts-check
+/** Widgets resource — CRUD over /api/v1/widgets. */
+
+export function buildWidgets(ctx) {
+  return {
+    /** @param {{ page?: number, limit?: number }} [params] */
+    list: ({ page, limit } = {}) => ctx.get('/api/v1/widgets', { searchParams: { page, limit } }),
+
+    /** @param {string} id */
+    get: (id) => ctx.get(`/api/v1/widgets/${id}`),
+
+    /** @param {{ title: string, type: string, retention_days?: number|null, config?: Object }} body */
+    create: (body) => ctx.post('/api/v1/widgets', body),
+
+    /** @param {string} id @param {{ title?: string, retention_days?: number|null, config?: Object }} patch */
+    update: (id, patch) => ctx.patch(`/api/v1/widgets/${id}`, patch),
+
+    /** @param {string} id */
+    delete: (id) => ctx.delete(`/api/v1/widgets/${id}`),
+  };
+}