mammoth-cli 2.2.71__tar.gz → 2.2.73__tar.gz

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.71
+Version: 2.2.73
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.2.71"
+__version__ = "2.2.73"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -123,6 +123,15 @@ mammoth dashboard descriptor-data DASHBOARD_ID --input '{"body": {"params": {
 A card that reads the same with and without the filter, or a distinct count
 that equals a row count, is a wrong binding, not a data fact.
 
+## Limits
+
+- `v3 generate` takes one `dataview_id`; `chat edit` cannot add a tile from
+  another view. Join the data into one view first.
+- The smallest date grain is day (day/week/month/quarter/year): hourly data
+  shows as daily points.
+- Currently a view with no numeric column gets no table or bar chart. Add a
+  numeric column such as a count, or build from a view that has a measure.
+
 ## Canvas, widget data and PDF
 
 `dashboard canvas get DASHBOARD_ID` reads the canvas (`data.canvas` incl.

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/index.md

@@ -14,6 +14,7 @@ hashes; stop on ambiguous schemas, authorization errors, or unknown effects.
 - [files, datasets, views and settings](resources.md)
 - [import a table from a database (SQL Server, MySQL, Postgres)](database-import.md)
 - [import a file from an SFTP server](file-import.md)
+- [pull data from a REST API or Elasticsearch on a schedule](rest-api-import.md)
 - [datasets in `need_action` or `needs_view` after upload](need-action.md)
 - [typed transformations and drafts](transforms.md)
 - [typed ETL discovery](typed-etl-discovery.md)

mammoth_cli-2.2.73/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/rest-api-import.md

@@ -0,0 +1,91 @@
+# Pull data from a REST API (or Elasticsearch) on a schedule
+
+REST connection -> dataset -> scheduled refresh. Every connector command runs
+in a project (`--project PROJECT_ID`). The connector key is `generic_rest_api`.
+Creates and refreshes are writes: get the user's confirmation first.
+
+```bash
+mammoth connector get generic_rest_api         # spec.connection_config (has base_url) + spec.connection_input_note; spec.data_source_config = JSON schema of the query keys below, plus selected_columns, max_flatten_depth, join_tables, loop_over
+mammoth connector connection list generic_rest_api   # reuse a connection if one fits
+```
+
+## 1. Connection
+
+The body goes under `config`, with **flat** auth fields: `auth_type` (`none`,
+`api_key`, `bearer`, `basic`), then `username` +
+`password`, or `token`, or `key_name` + `key_value` + `inject_into`
+(`header|query_param`). Do not send a nested `auth` object: an older backend
+drops it and saves the connection as `auth_type: none` (the target API then
+answers 401 at sample time); a backend with the fix rejects it with 4CONN003 ("Create a connection with auth as flat fields ... not a nested 'auth' object"). The base URL must be
+a public host; localhost and private addresses are refused (SSRF guard).
+
+```bash
+# request.json (mode 0600): {"config": {"name": "My API", "base_url": "https://api.example.com/v1", "auth_type": "basic", "username": "u", "password": "p"}}
+mammoth connector connection create generic_rest_api --input request.json --yes
+```
+
+The reply holds `identity_key`: that is CONNECTION_KEY below. To change
+credentials later use `connector connection update ... --input` with
+`{"credentials": {...}}`, not `config`. Error 4SUBS007 means the workspace plan
+does not include this connector (or its paid addon is not active).
+
+## 2. Try the data-source config (creates no dataset)
+
+`query` is a **JSON string** (not an object) of the data-source config:
+`endpoint_path`, `http_method` (`GET|POST`), `request_body`, `query_params`,
+`data_root_path` (JSONPath to the records; `[*]` is supported), `pagination`,
+`flatten_nested_json`, `max_pages`.
+
+```bash
+# sample.json: {"query": "{\"endpoint_path\": \"/posts\", \"data_root_path\": \"$\", \"max_pages\": 1}", "validate": false, "data_sample": true}
+mammoth connector ds-config create generic_rest_api CONNECTION_KEY --input sample.json --yes
+```
+
+Needs `--yes`; returns real sample rows (50 for a composite-agg
+`data_root_path`). Read the column names from `data.data_sample.dataschema`.
+`ds-config list generic_rest_api CONNECTION_KEY` shows the connection's configs
+(`config_key`, `ds_name`, `on_refresh_action`, `query`, `table`, `profile`);
+`ds-config get generic_rest_api CONNECTION_KEY CONFIG_KEY` returns one under
+`ds_config`. A REST config has `data_start_date: null`. A dataset's config key
+is `dataset get` -> `sources[0].details.id`.
+
+## 3. Dataset with a refresh schedule
+
+`schedule_properties` and `recurrence_info` are required; without them the job
+fails with "Invalid parameters". `on_refresh_action` is `replace` (swap the
+rows each refresh) or `combine` (append: every refresh re-adds every row the
+API returns, so rows duplicate).
+
+```bash
+# dataset.json
+# {"ds_creation_type": "cloud", "dataset_spec": {"connector_key": "generic_rest_api",
+#   "connection_key": "CONNECTION_KEY",
+#   "query_properties": {"ds_name": "My data", "table_name": "posts", "query": "<same JSON string as step 2>"},
+#   "schedule_properties": {"schedule_type": "moment", "first_pull_at": "now", "on_refresh_action": "replace"},
+#   "recurrence_info": {"interval": 1, "start_at": "2027-01-01T02:00:00"}}}
+mammoth dataset create --input dataset.json
+```
+
+## 4. Refresh automatically
+
+```bash
+# auto.json: {"description": "Refresh My data", "tasks": [{"task_type": "run_data_retrieval", "details": {"ds_details": [{"ds_id": DATASET_ID}]}}],
+#   "conditions": [{"condition_type": "at_specific_time", "details": {"frequency": "daily", "interval": 1, "start_at": "2027-01-01T02:00:00Z"}}]}
+mammoth automation create 'Refresh My data' --input auto.json --yes   # name required; ds_details must be a list
+mammoth automation update AUTOMATION_ID --yes --input '{"patch": [{"op": "command", "path": "run", "value": {}}]}'   # run now
+```
+
+A `start_at` under 2 minutes ahead is rejected ("too soon"); a past one starts now.
+More on automations: [recurring work](scheduling.md).
+
+## Elasticsearch
+
+Use the connection above with `base_url` of the cluster and `POST` on
+`/INDEX/_search`. Name the fields you need in `_source`: a field such as
+`asctime` ("2026-10-09 15:52:46,290", comma before the millis) breaks the load.
+
+- Documents: `"request_body": {"size": 500, "_source": ["@timestamp", "task"]}`,
+  `"data_root_path": "$.hits.hits[*]._source"`.
+- Counts per bucket: `"request_body": {"size": 0, "aggs": {"c": {"composite": {"size": 10000, "sources": [...]}}}}`,
+  `"data_root_path": "$.aggregations.c.buckets[*]"` gives columns `doc_count`,
+  `key.<source>`.

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/scheduling.md

@@ -120,7 +120,8 @@ If one exists, change it with `automation update AUTOMATION_ID` (see below)
 instead of creating another. Before a schedule that emails a client, send the
 same email to the user first (or `--dry-run` the create and show the
 recipients, subject and attached views) and get a yes. Give `start_at` a time
-in the future; a past `start_at` may fire straight away or never.
+in the future: under 2 minutes ahead is rejected ("too soon"), a later one is
+stored as sent, a past one starts now.
 
 ## Read it back
 

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/mammoth_cli/commands/auth.py

@@ -23,7 +23,7 @@ import typer
 from pydantic import ValidationError
 
 from mammoth_cli.context import credentials, oauth, profiles, resolver
-from mammoth_cli.context.endpoint import DEFAULT_SERVER_PREFIX, resolve_base_url
+from mammoth_cli.context.endpoint import resolve_base_url
 from mammoth_cli.context.resolver import ResolvedAuth, resolve_auth
 from mammoth_cli.contracts.auth import LoginRequest
 from mammoth_cli.errors.envelope import (
@@ -306,13 +306,9 @@ def _choose_method(
         return method
     if invocation.input_file is not None or blockers:
         return "token"
-    available = oauth.has_client_id(server_prefix)
-    prefix = server_prefix if server_prefix is not None else DEFAULT_SERVER_PREFIX
-    browser_note = "recommended" if available else f"(not yet available on {prefix})"
-    device_note = "no browser on this machine" if available else browser_note
     typer.echo("How do you want to sign in?", err=True)
-    typer.echo(f"  1) Browser (OAuth)      {browser_note}", err=True)
-    typer.echo(f"  2) Device code          {device_note}", err=True)
+    typer.echo("  1) Browser (OAuth)      recommended", err=True)
+    typer.echo("  2) Device code          no browser on this machine", err=True)
     typer.echo("  3) Paste an API token   for CI and scripts", err=True)
     if sys.stdin.isatty():
         return _choose_by_keypress()

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/mammoth_cli/commands/connector.py

@@ -360,7 +360,7 @@ def connector_connection_update(invocation: Invocation) -> HandlerResult:
 
 
 def connector_ds_config_create(invocation: Invocation) -> HandlerResult:
-    """Create a data source configuration. ``--yes`` is always required."""
+    """Sample a data source config; REST ``query`` is a JSON string. ``--yes`` always needed."""
     project_id = require_project(invocation)
     connector_key = _require_string_positional_at(invocation, 0, "connector key")
     connection_key = _require_string_positional_at(invocation, 1, "connection key")

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/mammoth_cli/commands/help_summaries.json

@@ -138,7 +138,7 @@
   "connector.connection.get": "Get one connection's details. Connector and connection keys are positional.",
   "connector.connection.list": "List connections for a connector type; find its key with `mammoth connector active`.",
   "connector.connection.update": "Update a connection's credentials. '--yes' is always required.",
-  "connector.ds-config.create": "Create a data source configuration. '--yes' is always required.",
+  "connector.ds-config.create": "Sample a data source config; REST 'query' is a JSON string. '--yes' always needed.",
   "connector.ds-config.delete": "Delete a data source configuration. Prompt or '--yes' required.",
   "connector.ds-config.delete-all": "Bulk-delete data source configurations for a connection. Prompt or '--yes' required.",
   "connector.ds-config.get": "Get one data source configuration by key.",

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/mammoth_cli/commands/schema.py

@@ -405,7 +405,8 @@ _COMMAND_DISCOVERY_PURPOSES = {
     ),
     "connector.get": (
         "connector database SQL Server MSSQL MySQL Postgres SFTP file server connection fields "
-        "host port username password required to connect import table file dataset"
+        "host port username password required to connect import table file dataset "
+        "REST API Elasticsearch generic_rest_api config schema"
     ),
     "connector.connection.list": (
         "which outside external sources connected connections list database SQL Server "
@@ -419,11 +420,12 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "connector.connection.create": (
         "connect a database such as SQL Server MSSQL MySQL Postgres Oracle or an SFTP file "
         "server host port username password new connection connector to import a table or "
-        "file into a dataset"
+        "file into a dataset, or a REST API or Elasticsearch generic_rest_api base_url"
     ),
     "connector.ds-config.create": (
         "import pull load read retrieve a table or SQL query from a connected database such "
-        "as SQL Server MSSQL MySQL Postgres connector connection as a new dataset rows data"
+        "as SQL Server MSSQL MySQL Postgres connector connection as a new dataset rows data "
+        "REST API Elasticsearch sample validate"
     ),
     "connector.ds-config.list": (
         "datasets imported from a connected database SQL Server MSSQL MySQL Postgres "
@@ -548,7 +550,8 @@ _COMMAND_DISCOVERY_PURPOSES = {
     # it just had no discovery-purpose text at all.
     "dataset.create": (
         "url web link fetch retrieve pull import public website endpoint api json data weburl "
-        "file csv from an SFTP server folder cloud storage connection connector as a new dataset"
+        "file csv from an SFTP server folder cloud storage connection connector as a new dataset "
+        "REST API Elasticsearch generic_rest_api on a schedule refresh recurring"
     ),
     "dashboard.v3.generate": (
         "create build make new generate dashboard board report from a view description "

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/mammoth_cli/context/oauth.py

@@ -37,19 +37,12 @@ from mammoth_cli.context import credentials
 from mammoth_cli.context.credentials import OAuthSession
 from mammoth_cli.context.endpoint import DEFAULT_SERVER_PREFIX, resolve_base_url
 from mammoth_cli.context.profiles import config_dir
-from mammoth_cli.errors.envelope import EXIT_AUTH, EXIT_USAGE, CliError
-
-#: The first-party CLI's OAuth client id, one constant per environment (the
-#: server prefix). The server allow-lists these ids, so they are not
-#: configurable at run time. An environment absent here has no CLI client yet.
-#: This table is the fallback for servers that do not publish
-#: ``mammoth_cli_client_id`` in their OAuth metadata (see
-#: :func:`published_client_id`); it is removed once every server publishes it.
-OAUTH_CLIENT_IDS: dict[str, str] = {
-    "challenger": "oc_aea5c2ce829da3f8",
-    "koyal": "oc_f2566336e235795c",
-    "app": "oc_b559f85cfb4de34c",
-}
+from mammoth_cli.errors.envelope import EXIT_AUTH, CliError
+
+#: The first-party CLI's OAuth client id: the same in every environment. The
+#: server publishes it in its OAuth metadata (see :func:`published_client_id`);
+#: this is the id used when it publishes nothing.
+BUILTIN_CLIENT_ID = "mammoth-cli"
 
 #: Refresh when the access token has less than this long to live.
 REFRESH_MARGIN_SECONDS = 120
@@ -59,7 +52,6 @@ _LOCK_POLL_SECONDS = 0.1
 _LOCK_WAIT_SECONDS = 60.0
 
 CODE_LOGIN_EXPIRED = "login_expired"
-CODE_OAUTH_UNAVAILABLE = "oauth_unavailable"
 CODE_OAUTH_LOGIN_FAILED = "oauth_login_failed"
 CODE_DEVICE_LOGIN_EXPIRED = "device_login_expired"
 
@@ -92,7 +84,7 @@ def published_client_id(prefix: str) -> str | None:
 
     One GET per environment per process. None when the field is absent, the
     server cannot be reached, or it answers anything but metadata: the caller
-    then falls back to :data:`OAUTH_CLIENT_IDS`.
+    then uses :data:`BUILTIN_CLIENT_ID`.
     """
     from mammoth import oauth as sdk_oauth
 
@@ -108,36 +100,10 @@ def published_client_id(prefix: str) -> str | None:
     return value if isinstance(value, str) and value else None
 
 
-def _resolve_client_id(server_prefix: str | None) -> str | None:
-    prefix = server_prefix if server_prefix is not None else DEFAULT_SERVER_PREFIX
-    return published_client_id(prefix) or OAUTH_CLIENT_IDS.get(prefix)
-
-
-def has_client_id(server_prefix: str | None) -> bool:
-    """Whether the CLI has an OAuth client for this environment.
-
-    Makes a network call (cached per process): call it only on login paths.
-    """
-    return _resolve_client_id(server_prefix) is not None
-
-
 def client_id_for(server_prefix: str | None) -> str:
-    """Return the CLI's OAuth client id for one environment.
-
-    Raises:
-        CliError: ``oauth_unavailable`` when the environment has no CLI client.
-    """
-    client_id = _resolve_client_id(server_prefix)
-    if client_id is not None:
-        return client_id
+    """Return the CLI's OAuth client id: the published one, else the built-in one."""
     prefix = server_prefix if server_prefix is not None else DEFAULT_SERVER_PREFIX
-    raise CliError(
-        code=CODE_OAUTH_UNAVAILABLE,
-        message=f"Browser sign-in is not available on '{prefix}' yet.",
-        exit_status=EXIT_USAGE,
-        hint="Pick option 3 (paste an API token) or run: mammoth auth login --method token",
-        recovery_commands=["mammoth auth login --method token"],
-    )
+    return published_client_id(prefix) or BUILTIN_CLIENT_ID
 
 
 # --- PKCE ---------------------------------------------------------------------

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/mammoth_cli/errors/envelope.py

@@ -161,7 +161,6 @@ ERROR_SUMMARIES: dict[str, str] = {
     "not_authenticated": _S_SIGN_IN,
     "not_implemented": _S_UNAVAILABLE,
     "oauth_login_failed": "The browser sign-in didn't complete.",
-    "oauth_unavailable": "Browser sign-in isn't available on this server.",
     "oauth_grant_revoke_failed": "The server did not revoke this sign-in grant.",
     "outcome_unknown": "It isn't clear whether this step went through. Check before trying again.",
     "pipeline_changed": "The pipeline was changed by someone else while this step ran.",

{mammoth_cli-2.2.71 → mammoth_cli-2.2.73}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mammoth-cli"
-version = "2.2.71"
+version = "2.2.73"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"