databar 2.0.2__tar.gz → 2.0.4__tar.gz

{databar-2.0.2/src/databar.egg-info → databar-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databar
-Version: 2.0.2
+Version: 2.0.4
 Summary: Official Databar.ai Python SDK and CLI — connect to enrichments, waterfalls, and tables via api.databar.ai
 Author-email: "Databar.ai Team" <info@databar.ai>
 License: MIT License

{databar-2.0.2 → databar-2.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "databar"
-version = "2.0.2"
+version = "2.0.4"
 description = "Official Databar.ai Python SDK and CLI — connect to enrichments, waterfalls, and tables via api.databar.ai"
 readme = "README.md"
 license = { file = "LICENSE" }

{databar-2.0.2 → databar-2.0.4}/src/databar/__init__.py

@@ -57,7 +57,7 @@ from .models import (
     WaterfallEnrichment,
 )
 
-__version__ = "2.0.2"
+__version__ = "2.0.4"
 __all__ = [
     "DatabarClient",
     # exceptions

{databar-2.0.2 → databar-2.0.4}/src/databar/client.py

@@ -16,6 +16,7 @@ in databar_mcp/src/databar-client.ts.
 from __future__ import annotations
 
 import os
+import re
 import time
 from typing import Any, Dict, List, Optional
 
@@ -438,10 +439,65 @@ class DatabarClient:
         table_uuid: str,
         enrichment_id: int,
         mapping: Dict[str, Any],
-    ) -> Any:
-        """Add an enrichment to a table with a parameter-to-column mapping."""
-        payload = {"enrichment": enrichment_id, "mapping": mapping}
-        return self._request("POST", f"/table/{table_uuid}/add-enrichment", json=payload)
+    ) -> TableEnrichment:
+        """
+        Add an enrichment to a table with a parameter-to-column mapping.
+
+        ``mapping`` keys are enrichment parameter names. Values are dicts with:
+          - ``{"type": "mapping", "value": "<column-name-or-uuid>"}``
+            — reads the value from a table column per row.
+            You may pass a human-readable column name; the SDK will automatically
+            resolve it to the required column UUID via GET /table/{uuid}/columns.
+          - ``{"type": "simple", "value": "<static-value>"}``
+            — uses the same hardcoded value for every row.
+
+        Returns the newly added :class:`TableEnrichment` (with ``id`` and ``name``),
+        resolved by diffing enrichments before and after the add.
+        """
+        # Auto-resolve column names → UUIDs for mapping-type entries
+        resolved_mapping: Dict[str, Any] = {}
+        column_map: Optional[Dict[str, str]] = None  # name → uuid, built lazily
+
+        for param, entry in mapping.items():
+            if not isinstance(entry, dict) or entry.get("type") != "mapping":
+                resolved_mapping[param] = entry
+                continue
+
+            value = entry.get("value", "")
+            # Looks like a UUID already — 8-4-4-4-12 hex pattern
+            if re.fullmatch(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", str(value), re.IGNORECASE):
+                resolved_mapping[param] = entry
+                continue
+
+            # Build the column name→uuid map once
+            if column_map is None:
+                columns = self.get_columns(table_uuid)
+                column_map = {c.name: c.identifier for c in columns}
+
+            uuid = column_map.get(value)
+            if uuid is None:
+                # Not a known column name — pass through and let the API surface the error
+                resolved_mapping[param] = entry
+            else:
+                resolved_mapping[param] = {**entry, "value": uuid}
+
+        # Snapshot existing enrichment IDs so we can detect the new one
+        before_ids = {e.id for e in self.get_table_enrichments(table_uuid)}
+
+        payload = {"enrichment": enrichment_id, "mapping": resolved_mapping}
+        self._request("POST", f"/table/{table_uuid}/add-enrichment", json=payload)
+
+        # Fetch updated list and return the newly created TableEnrichment
+        after = self.get_table_enrichments(table_uuid)
+        new_enrichments = [e for e in after if e.id not in before_ids]
+        if new_enrichments:
+            return new_enrichments[-1]
+
+        # Fallback: return the last enrichment in the list if we can't detect which is new
+        if after:
+            return after[-1]
+
+        raise DatabarError("Enrichment was added but could not be retrieved. Use get_table_enrichments() to fetch it manually.")
 
     def run_table_enrichment(
         self,
@@ -465,9 +521,16 @@ class DatabarClient:
         self,
         table_uuid: str,
         page: int = 1,
-        per_page: int = 1000,
+        per_page: int = 100,
     ) -> Dict[str, Any]:
-        """Get rows from a table with pagination. Returns raw dict with has_next_page etc."""
+        """
+        Get rows from a table with pagination.
+
+        Returns a dict with keys: ``data`` (list of row dicts), ``has_next_page``,
+        ``total_count``, ``page``.  Each row dict is keyed by column name.
+
+        ``per_page`` max is 500 (API limit). Default is 100.
+        """
         return self._request(
             "GET",
             f"/table/{table_uuid}/rows",

{databar-2.0.2 → databar-2.0.4}/src/databar/models.py

@@ -20,6 +20,11 @@ from pydantic import BaseModel, Field
 
 
 class User(BaseModel):
+    """Authenticated user profile.
+
+    Fields: first_name, email, balance, plan.
+    """
+
     first_name: Optional[str] = None
     email: str
     balance: float
@@ -51,22 +56,64 @@ class Choices(BaseModel):
 
 
 class EnrichmentParam(BaseModel):
-    name: str
-    is_required: bool
+    """A parameter required or accepted by an enrichment.
+
+    Fields: name, is_required, type_field, description, choices.
+
+    Property aliases: .slug → .name, .label → .description, .required → .is_required.
+    """
+
+    name: str = Field(description="Parameter slug used as the key in the params dict.")
+    is_required: bool = Field(description="Whether this parameter is required.")
     type_field: str = Field(
         description="Input type. Common values: text, select, mselect, datetime."
     )
-    description: str
+    description: str = Field(description="Human-readable label / description.")
     choices: Optional[Choices] = None
 
+    @property
+    def slug(self) -> str:
+        """Alias for name."""
+        return self.name
+
+    @property
+    def label(self) -> str:
+        """Alias for description."""
+        return self.description
+
+    @property
+    def required(self) -> bool:
+        """Alias for is_required."""
+        return self.is_required
+
 
 class EnrichmentResponseField(BaseModel):
-    name: str
-    type_field: str
+    """A field returned in the enrichment result data.
+
+    Fields: name, type_field.
+
+    Property aliases: .slug → .name, .label → .name.
+    """
+
+    name: str = Field(description="Field name as it appears in the result data.")
+    type_field: str = Field(description="Data type of this field.")
+
+    @property
+    def slug(self) -> str:
+        """Alias for name."""
+        return self.name
+
+    @property
+    def label(self) -> str:
+        """Alias for name."""
+        return self.name
 
 
 class EnrichmentSummary(BaseModel):
-    """Enrichment as returned by the list endpoint (no params/response_fields)."""
+    """Enrichment as returned by the list endpoint (no params/response_fields).
+
+    Fields: id, name, description, data_source, price, auth_method.
+    """
 
     id: int
     name: str
@@ -77,7 +124,16 @@ class EnrichmentSummary(BaseModel):
 
 
 class Enrichment(EnrichmentSummary):
-    """Full enrichment detail including params and response fields."""
+    """Full enrichment detail including params and response fields.
+
+    Fields: id, name, description, data_source, price, auth_method, params, response_fields.
+
+    Usage::
+
+        enrichment = client.get_enrichment(123)
+        for p in enrichment.params:
+            print(p.name, p.is_required, p.description)
+    """
 
     params: Optional[List[EnrichmentParam]] = None
     response_fields: Optional[List[EnrichmentResponseField]] = None
@@ -153,7 +209,20 @@ class WaterfallEnrichment(BaseModel):
 
 
 class Waterfall(BaseModel):
-    identifier: str
+    """A waterfall enrichment that tries multiple providers in sequence.
+
+    Fields: identifier, name, description, input_params, output_fields,
+    available_enrichments, is_email_verifying, email_verifiers.
+
+    Property aliases: .slug → .identifier.
+
+    Usage::
+
+        wf = client.get_waterfall("email_getter")
+        result = client.run_waterfall_sync(wf.identifier, {...})
+    """
+
+    identifier: str = Field(description="Slug-style identifier, e.g. 'email_getter'. Use this when calling run_waterfall().")
     name: str
     description: str
     input_params: List[Dict[str, Any]]
@@ -162,6 +231,11 @@ class Waterfall(BaseModel):
     is_email_verifying: bool
     email_verifiers: List[Any]
 
+    @property
+    def slug(self) -> str:
+        """Alias for identifier."""
+        return self.identifier
+
 
 # ===========================================================================
 # Tables
@@ -169,21 +243,56 @@ class Waterfall(BaseModel):
 
 
 class Table(BaseModel):
-    identifier: str
+    """A Databar table.
+
+    Fields: identifier, name, created_at, updated_at.
+
+    Property aliases: .id → .identifier, .uuid → .identifier.
+
+    Usage::
+
+        table = client.create_table(name="Leads", columns=["email", "name"])
+        rows = client.get_rows(table.identifier)
+    """
+
+    identifier: str = Field(description="Table UUID. Use this in all table operations.")
     name: str
     created_at: str
     updated_at: str
 
+    @property
+    def id(self) -> str:
+        """Alias for identifier."""
+        return self.identifier
+
+    @property
+    def uuid(self) -> str:
+        """Alias for identifier."""
+        return self.identifier
+
 
 class Column(BaseModel):
-    identifier: str
+    """A column defined on a table.
+
+    Fields: identifier, internal_name, name, type_of_value, data_processor_id.
+    """
+
+    identifier: str = Field(description="Column UUID.")
     internal_name: str
-    name: str
+    name: str = Field(description="Human-readable column name.")
     type_of_value: str
     data_processor_id: Optional[int] = None
 
 
 class TableEnrichment(BaseModel):
+    """An enrichment configured on a table.
+
+    Fields: id, name.
+
+    The id here is the TABLE-ENRICHMENT id — use it with run_table_enrichment(),
+    not the enrichment catalog id.
+    """
+
     id: int
     name: str
 

{databar-2.0.2 → databar-2.0.4/src/databar.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databar
-Version: 2.0.2
+Version: 2.0.4
 Summary: Official Databar.ai Python SDK and CLI — connect to enrichments, waterfalls, and tables via api.databar.ai
 Author-email: "Databar.ai Team" <info@databar.ai>
 License: MIT License

{databar-2.0.2 → databar-2.0.4}/tests/test_cli.py

@@ -329,4 +329,4 @@ def test_task_get_poll(monkeypatch):
 def test_version_flag():
     result = runner.invoke(app, ["--version"])
     assert result.exit_code == 0
-    assert "2.0.2" in result.output
+    assert "2.0.4" in result.output