convexity-sdk 0.12.0.dev237__tar.gz → 0.12.0.dev239__tar.gz

{convexity_sdk-0.12.0.dev237 → convexity_sdk-0.12.0.dev239}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: convexity-sdk
-Version: 0.12.0.dev237
+Version: 0.12.0.dev239
 Summary: Convexity Python SDK - programmatic access to the Convexity platform
 Requires-Python: >=3.12
 Requires-Dist: convexity-api-client<0.13.0,>=0.12.0.dev0

{convexity_sdk-0.12.0.dev237 → convexity_sdk-0.12.0.dev239}/convexity_sdk/resources/organizations.py

@@ -69,12 +69,12 @@ class Organizations:
         self,
         organization_id: str,
         *,
-        user_id: str,
+        email: str,
         role: OrganizationRole = OrganizationRole.MEMBER,
     ) -> OrganizationMemberResponse:
-        """Add a member to an organization."""
+        """Add a member to an organization by email."""
         body = AddOrganizationMemberRequest(
-            user_id=user_id,
+            email=email,
             role=role,
         )
         result = _add_member.sync(organization_id, client=self._client, body=body)

{convexity_sdk-0.12.0.dev237 → convexity_sdk-0.12.0.dev239}/convexity_sdk/resources/projects.py

@@ -18,6 +18,7 @@ from convexity_api_client.api.v1 import (
 from convexity_api_client.api.v1 import (
     list_user_projects_v1_projects_get as _list_projects,
 )
+from convexity_api_client.errors import UnexpectedStatus
 from convexity_api_client.models.create_project_request import CreateProjectRequest
 from convexity_api_client.models.project_list_response import ProjectListResponse
 from convexity_api_client.models.project_response import ProjectResponse
@@ -56,7 +57,12 @@ class Projects:
 
     def get_by_slug(self, organization_id: str, slug: str) -> ProjectResponse | None:
         """Get a single project by slug within an organization."""
-        result = _get_project_by_slug.sync(organization_id, slug, client=self._client)
+        try:
+            result = _get_project_by_slug.sync(organization_id, slug, client=self._client)
+        except UnexpectedStatus as exc:
+            if exc.status_code == 404:
+                return None
+            raise
         if isinstance(result, ProjectResponse):
             return result
         return None

convexity_sdk-0.12.0.dev239/samples/README.md

@@ -0,0 +1,31 @@
+git pull# Convexity SDK Samples
+
+This directory contains sample scripts demonstrating how to use the Convexity SDK.
+
+## Samples
+
+| Sample                                                                                     | Description                                             |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
+| [getting_started.py](getting_started.py)                                                   | Basic SDK setup and usage                               |
+| [create_org_and_project.py](create_org_and_project.py)                                     | Create an organization and project                      |
+| [create_databricks_connections.py](create_databricks_connections.py)                       | Create Databricks connections                           |
+| [create_datasets.py](create_datasets.py)                                                   | Create datasets from Databricks connections             |
+| [create_dashboards.py](create_dashboards.py)                                               | Create analytic dashboards with widgets                 |
+| [share_dashboard.py](share_dashboard.py)                                                   | Share a dashboard with other users                      |
+| [list_orgs_and_projects.py](list_orgs_and_projects.py)                                     | List organizations and projects                         |
+| [query_datalake.py](query_datalake.py)                                                     | Query the DuckLake warehouse with DuckDB                |
+| [cancel_refresh_task.py](cancel_refresh_task.py)                                           | Cancel a pending dataset refresh task                   |
+| [create_forecast_task.py](create_forecast_task.py)                                         | Create a demand-forecasting task and run it             |
+| [compare_api_key_scopes.py](compare_api_key_scopes.py)                                     | Compare READ vs ADMIN API key behavior                  |
+| [debug_api_key_tenant_context.py](debug_api_key_tenant_context.py)                         | Diagnose API key tenant/scope mismatch                  |
+| [quickbook/001_check_quickbook_connection.py](quickbook/001_check_quickbook_connection.py) | Verify a QuickBooks connection before creating datasets |
+| [quickbook/002_create_quickbook_datasets.py](quickbook/002_create_quickbook_datasets.py)   | Create and refresh QuickBooks-backed datasets           |
+| [shopify/001_check_shopify_connection.py](shopify/001_check_shopify_connection.py)         | Verify a Shopify connection before creating datasets    |
+| [shopify/002_create_shopify_datasets.py](shopify/002_create_shopify_datasets.py)           | Create and refresh Shopify-backed datasets              |
+
+## Running Samples
+
+```bash
+# From the repo root
+uv run python packages/convexity-sdk/samples/getting_started.py
+```

convexity_sdk-0.12.0.dev239/samples/create_org_and_project.py

@@ -0,0 +1,78 @@
+"""
+Convexity SDK - Create Organization & Project
+
+This sample demonstrates how to:
+- Create or reuse an organization
+- Optionally add members to the organization as admins by email
+- Create or reuse a project within the organization
+
+Prerequisites:
+- A valid API key with WRITE or ADMIN permission
+
+Optional environment variables:
+- CONVEXITY_SAMPLE_ADMIN_EMAILS: comma-separated emails to add as admins
+"""
+
+import os
+
+from convexity_api_client.errors import UnexpectedStatus
+from convexity_api_client.models.organization_role import OrganizationRole
+
+from convexity_sdk import ConvexityClient
+
+ORG_SLUG = "convexity-sdk-samples"
+PROJECT_SLUG = "griffin-it"
+ADMIN_EMAILS = [email.strip() for email in os.getenv("CONVEXITY_SAMPLE_ADMIN_EMAILS", "").split(",") if email.strip()]
+
+client = ConvexityClient()
+
+try:
+    # ── Step 1: Create or reuse an organization ─────────────────────────
+    org = client.organizations.get_by_slug(ORG_SLUG)
+    if org is None:
+        org = client.organizations.create(
+            name="Convexity SDK samples",
+            slug=ORG_SLUG,
+            description="Organization created by the Convexity SDK sample scripts",
+        )
+        print(f"Created organization: {org.name} (id={org.id})")
+    else:
+        print(f"Found organization: {org.name} (id={org.id})")
+
+    # ── Step 2: Optionally add admin members ────────────────────────────
+    if not ADMIN_EMAILS:
+        print("No admin emails configured; skipping member invite step.")
+        print("Set CONVEXITY_SAMPLE_ADMIN_EMAILS=email1@example.com,email2@example.com to add admins.")
+
+    for email in ADMIN_EMAILS:
+        try:
+            member = client.organizations.add_member(
+                org.id,
+                email=email,
+                role=OrganizationRole.ADMIN,
+            )
+        except UnexpectedStatus as exc:
+            detail = exc.content.decode(errors="ignore")
+            if exc.status_code == 400 and "already a member" in detail:
+                print(f"  Admin already exists: {email}")
+                continue
+            print(f"  Skipped admin {email}: {detail}")
+            continue
+        print(f"  Added admin: {email} (user_id={member.user_id}, role={member.role})")
+
+    # ── Step 3: Create or reuse a project in the organization ───────────
+    project = client.projects.get_by_slug(org.id, PROJECT_SLUG)
+    if project is None:
+        project = client.projects.create(
+            name="griffin it",
+            slug=PROJECT_SLUG,
+            organization_id=org.id,
+            description="Test project created by the Convexity SDK sample scripts",
+        )
+        print(f"Created project: {project.name} (id={project.id})")
+    else:
+        print(f"Found project: {project.name} (id={project.id})")
+
+    print("\nDone!")
+finally:
+    client.close()

convexity_sdk-0.12.0.dev239/samples/quickbook/001_check_quickbook_connection.py

@@ -0,0 +1,142 @@
+"""
+Convexity SDK - Check QuickBooks Connection
+
+This sample verifies that a QuickBooks connection exists for a project and can
+connect successfully. Run this before creating QuickBooks-backed datasets.
+
+Prerequisites:
+- A valid API key with READ permission for listing connections.
+- WRITE or ADMIN permission if you want the sample to run the live verify step.
+- An existing organization and project.
+  Run ../create_org_and_project.py first if needed.
+- A QuickBooks connection created manually in Convexity.
+
+Optional environment variables:
+- QUICKBOOKS_ORG_SLUG: organization slug, defaults to convexity-sdk-samples
+- QUICKBOOKS_PROJECT_SLUG: project slug, defaults to griffin-it
+- QUICKBOOKS_CONNECTION_NAME: when set, require this exact connection name
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+from convexity_sdk import ConvexityClient
+from convexity_sdk.exceptions import ConvexityError
+
+ORG_SLUG = os.getenv("QUICKBOOKS_ORG_SLUG", "convexity-sdk-samples")
+PROJECT_SLUG = os.getenv("QUICKBOOKS_PROJECT_SLUG", "griffin-it")
+QUICKBOOKS_CONNECTION_NAME = os.getenv("QUICKBOOKS_CONNECTION_NAME")
+
+
+def find_project_id(client: ConvexityClient) -> str:
+    org = client.organizations.get_by_slug(ORG_SLUG)
+    if org is None:
+        print(f"Organization '{ORG_SLUG}' not found. Run ../create_org_and_project.py first.", file=sys.stderr)
+        sys.exit(1)
+
+    project = client.projects.get_by_slug(org.id, PROJECT_SLUG)
+    if project is None:
+        print(f"Project '{PROJECT_SLUG}' not found in organization '{ORG_SLUG}'.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Using project: {project.name} ({project.id})")
+    return project.id
+
+
+def connection_to_dict(connection: Any) -> dict[str, Any]:
+    if hasattr(connection, "to_dict"):
+        data = connection.to_dict()
+        if isinstance(data, dict):
+            return data
+    return {}
+
+
+def find_quickbooks_connection(client: ConvexityClient, project_id: str) -> dict[str, Any] | None:
+    connections = client.connections.list(project_id=project_id).connections
+    quickbooks_connections = []
+    for connection in connections:
+        data = connection_to_dict(connection)
+        if data.get("type") == "QUICKBOOKS":
+            quickbooks_connections.append(data)
+
+    if QUICKBOOKS_CONNECTION_NAME is not None:
+        return next(
+            (connection for connection in quickbooks_connections if connection.get("name") == QUICKBOOKS_CONNECTION_NAME),
+            None,
+        )
+
+    return quickbooks_connections[0] if quickbooks_connections else None
+
+
+def ask_user_to_create_connection(project_id: str) -> None:
+    print("QuickBooks connection is not available for this project.", file=sys.stderr)
+    print("Please create and connect a QuickBooks connection manually in Convexity, then rerun this sample.", file=sys.stderr)
+    print(f"Project ID: {project_id}", file=sys.stderr)
+    if QUICKBOOKS_CONNECTION_NAME is not None:
+        print(f"Expected connection name: {QUICKBOOKS_CONNECTION_NAME}", file=sys.stderr)
+
+
+def verify_quickbooks_connection(client: ConvexityClient, connection_id: str) -> dict[str, Any]:
+    response = client._http.request("post", f"/v1/connections/quickbooks/{connection_id}/verify")
+    data = response.json()
+    if not isinstance(data, dict):
+        raise ValueError(f"Unexpected QuickBooks verify response: {data!r}")
+    return data
+
+
+def main() -> None:
+    client = ConvexityClient()
+    try:
+        print(f"Connected to {client.base_url}")
+        project_id = find_project_id(client)
+
+        connection = find_quickbooks_connection(client, project_id)
+        if connection is None:
+            ask_user_to_create_connection(project_id)
+            sys.exit(1)
+
+        connection_id = connection.get("id")
+        if not isinstance(connection_id, str) or not connection_id:
+            print(f"QuickBooks connection '{connection.get('name')}' has no connection ID.", file=sys.stderr)
+            ask_user_to_create_connection(project_id)
+            sys.exit(1)
+
+        print(f"Found QuickBooks connection: {connection.get('name')} ({connection_id})")
+        if connection.get("realmId"):
+            print(f"Realm ID: {connection['realmId']}")
+        if connection.get("environment"):
+            print(f"Environment: {connection['environment']}")
+        if connection.get("status"):
+            print(f"Stored status: {connection['status']}")
+
+        try:
+            verified = verify_quickbooks_connection(client, connection_id)
+        except ConvexityError as exc:
+            print(f"QuickBooks verification failed: {exc}", file=sys.stderr)
+            print("Please reconnect or recreate the QuickBooks connection manually in Convexity, then rerun this sample.", file=sys.stderr)
+            sys.exit(1)
+
+        status = verified.get("status")
+        if status != "CONNECTED":
+            print(f"QuickBooks connection is not connected. Current status: {status or 'unknown'}", file=sys.stderr)
+            if verified.get("errorMessage"):
+                print(f"Error: {verified['errorMessage']}", file=sys.stderr)
+            print("Please reconnect or recreate the QuickBooks connection manually in Convexity, then rerun this sample.", file=sys.stderr)
+            sys.exit(1)
+
+        print("QuickBooks connection is available and connected.")
+        if verified.get("realmId"):
+            print(f"Realm ID: {verified['realmId']}")
+        if verified.get("oauthScopes"):
+            print("OAuth scopes:")
+            for scope in verified["oauthScopes"]:
+                print(f"  - {scope}")
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    main()

convexity_sdk-0.12.0.dev239/samples/quickbook/002_create_quickbook_datasets.py

@@ -0,0 +1,266 @@
+"""
+Convexity SDK - Create QuickBooks Datasets
+
+This sample creates QuickBooks-backed datasets from an existing QuickBooks
+connection, refreshes them, and prints a small sanity check for row count and
+schema.
+
+Prerequisites:
+- Run 001_check_quickbook_connection.py first.
+- A valid API key with WRITE or ADMIN permission.
+- A connected QuickBooks connection in the target project.
+
+Optional environment variables:
+- QUICKBOOKS_ORG_SLUG: organization slug, defaults to convexity-sdk-samples
+- QUICKBOOKS_PROJECT_SLUG: project slug, defaults to griffin-it
+- QUICKBOOKS_CONNECTION_NAME: when set, require this exact connection name
+- QUICKBOOKS_DATASET_ENTITIES: comma-separated QuickBooks entities, defaults to all supported entities
+- QUICKBOOKS_REFRESH_TIMEOUT_SECONDS: refresh timeout per dataset, defaults to 180
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from typing import Any
+
+from convexity_api_client.errors import UnexpectedStatus
+from convexity_api_client.models.dataset_config import DatasetConfig
+from convexity_api_client.models.dataset_definition import DatasetDefinition
+from convexity_api_client.models.dataset_type import DatasetType
+from convexity_api_client.models.quick_books_dataset_config import QuickBooksDatasetConfig
+from convexity_api_client.models.quick_books_entity import QuickBooksEntity
+from convexity_api_client.models.refresh_dataset_payload import RefreshDatasetPayload
+from convexity_api_client.models.refresh_mode import RefreshMode
+from convexity_api_client.models.worker_task_status import WorkerTaskStatus
+from convexity_api_client.types import Unset
+
+from convexity_sdk import ConvexityClient
+from convexity_sdk.exceptions import ConvexityError
+
+ORG_SLUG = os.getenv("QUICKBOOKS_ORG_SLUG", "convexity-sdk-samples")
+PROJECT_SLUG = os.getenv("QUICKBOOKS_PROJECT_SLUG", "griffin-it")
+QUICKBOOKS_CONNECTION_NAME = os.getenv("QUICKBOOKS_CONNECTION_NAME")
+DEFAULT_QUICKBOOKS_DATASET_ENTITIES = ",".join(entity.value for entity in QuickBooksEntity)
+QUICKBOOKS_DATASET_ENTITIES = os.getenv("QUICKBOOKS_DATASET_ENTITIES", DEFAULT_QUICKBOOKS_DATASET_ENTITIES)
+REFRESH_TIMEOUT_SECONDS = int(os.getenv("QUICKBOOKS_REFRESH_TIMEOUT_SECONDS", "180"))
+POLL_INTERVAL_SECONDS = 5
+
+
+def parse_entities() -> list[QuickBooksEntity]:
+    entities: list[QuickBooksEntity] = []
+    for raw_entity in QUICKBOOKS_DATASET_ENTITIES.split(","):
+        entity_name = raw_entity.strip()
+        if not entity_name:
+            continue
+        try:
+            entities.append(QuickBooksEntity(entity_name))
+        except ValueError:
+            valid = ", ".join(entity.value for entity in QuickBooksEntity)
+            print(f"Unknown QuickBooks entity '{entity_name}'. Valid values: {valid}", file=sys.stderr)
+            sys.exit(1)
+    if not entities:
+        print("QUICKBOOKS_DATASET_ENTITIES did not include any entities.", file=sys.stderr)
+        sys.exit(1)
+    return entities
+
+
+def find_project_id(client: ConvexityClient) -> str:
+    org = client.organizations.get_by_slug(ORG_SLUG)
+    if org is None:
+        print(f"Organization '{ORG_SLUG}' not found. Run ../create_org_and_project.py first.", file=sys.stderr)
+        sys.exit(1)
+
+    project = client.projects.get_by_slug(org.id, PROJECT_SLUG)
+    if project is None:
+        print(f"Project '{PROJECT_SLUG}' not found in organization '{ORG_SLUG}'.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Using project: {project.name} ({project.id})")
+    return project.id
+
+
+def connection_to_dict(connection: Any) -> dict[str, Any]:
+    if hasattr(connection, "to_dict"):
+        data = connection.to_dict()
+        if isinstance(data, dict):
+            return data
+    return {}
+
+
+def find_quickbooks_connection(client: ConvexityClient, project_id: str) -> dict[str, Any] | None:
+    connections = client.connections.list(project_id=project_id).connections
+    quickbooks_connections = []
+    for connection in connections:
+        data = connection_to_dict(connection)
+        if data.get("type") == "QUICKBOOKS":
+            quickbooks_connections.append(data)
+
+    if QUICKBOOKS_CONNECTION_NAME is not None:
+        return next(
+            (connection for connection in quickbooks_connections if connection.get("name") == QUICKBOOKS_CONNECTION_NAME),
+            None,
+        )
+
+    return quickbooks_connections[0] if quickbooks_connections else None
+
+
+def verify_quickbooks_connection(client: ConvexityClient, connection_id: str) -> dict[str, Any]:
+    response = client._http.request("post", f"/v1/connections/quickbooks/{connection_id}/verify")
+    data = response.json()
+    if not isinstance(data, dict):
+        raise ValueError(f"Unexpected QuickBooks verify response: {data!r}")
+    return data
+
+
+def dataset_name_for(entity: QuickBooksEntity) -> str:
+    return f"quickbooks_{entity.value.lower()}"
+
+
+def build_config(entity: QuickBooksEntity) -> DatasetConfig:
+    return DatasetConfig(quickbooks=QuickBooksDatasetConfig(entity=entity))
+
+
+def find_existing_dataset(client: ConvexityClient, project_id: str, name: str) -> DatasetDefinition | None:
+    datasets = client.datasets.list(project_id).datasets
+    return next((dataset for dataset in datasets if dataset.name == name), None)
+
+
+def create_or_update_dataset(
+    client: ConvexityClient,
+    *,
+    project_id: str,
+    connection_id: str,
+    entity: QuickBooksEntity,
+) -> DatasetDefinition:
+    name = dataset_name_for(entity)
+    config = build_config(entity)
+    existing = find_existing_dataset(client, project_id, name)
+    if existing is not None:
+        dataset = client.datasets.update(
+            existing.id,
+            connection_id=connection_id,
+            config=config,
+            refresh_mode=RefreshMode.MANUAL,
+        )
+        print(f"Updated dataset: {dataset.name} ({dataset.id})")
+        return dataset
+
+    dataset = client.datasets.create(
+        project_id=project_id,
+        name=name,
+        type_=DatasetType.QUICKBOOKS,
+        config=config,
+        connection_id=connection_id,
+        refresh_mode=RefreshMode.MANUAL,
+        description=f"QuickBooks {entity.value} dataset created by the SDK sample",
+        tags=["quickbooks", "sdk-sample"],
+    )
+    print(f"Created dataset: {dataset.name} ({dataset.id})")
+    return dataset
+
+
+def refresh_and_wait(client: ConvexityClient, dataset: DatasetDefinition) -> RefreshDatasetPayload:
+    try:
+        task = client.datasets.refresh(dataset.id)
+    except (UnexpectedStatus, ConvexityError, ValueError) as exc:
+        raise RuntimeError(f"Failed to trigger refresh for '{dataset.name}': {exc}") from exc
+
+    print(f"  Refresh started (task_id={task.id})", end="", flush=True)
+    deadline = time.monotonic() + REFRESH_TIMEOUT_SECONDS
+    while True:
+        if time.monotonic() > deadline:
+            raise TimeoutError(f"Refresh timed out for '{dataset.name}' after {REFRESH_TIMEOUT_SECONDS} seconds")
+
+        time.sleep(POLL_INTERVAL_SECONDS)
+        state = client.datasets.get_refresh_status(dataset.id, task.id)
+        payload = state.payload
+        if isinstance(payload, RefreshDatasetPayload):
+            message = payload.progress_message if not isinstance(payload.progress_message, Unset) else None
+            if message:
+                print(f" {message}", end="", flush=True)
+        else:
+            payload = None
+
+        if state.status == WorkerTaskStatus.COMPLETED:
+            print(" COMPLETED")
+            if payload is None:
+                raise ValueError(f"Refresh completed for '{dataset.name}' without a refresh payload")
+            return payload
+
+        if state.status == WorkerTaskStatus.FAILED:
+            error = state.error if not isinstance(state.error, Unset) else "unknown error"
+            raise RuntimeError(f"Refresh failed for '{dataset.name}': {error}")
+
+        if state.status == WorkerTaskStatus.CANCELLED:
+            raise RuntimeError(f"Refresh was cancelled for '{dataset.name}'")
+
+        print(".", end="", flush=True)
+
+
+def print_dataset_sanity(client: ConvexityClient, dataset: DatasetDefinition, payload: RefreshDatasetPayload) -> None:
+    refreshed = client.datasets.get(dataset.id)
+    if refreshed is None:
+        raise ValueError(f"Could not fetch refreshed dataset '{dataset.name}'")
+
+    row_count = payload.row_count if not isinstance(payload.row_count, Unset) else None
+    schema = refreshed.schema
+    columns = [] if schema is None or isinstance(schema, Unset) else schema
+
+    print(f"  Rows written: {row_count if row_count is not None else 'unknown'}")
+    print(f"  Columns: {len(columns)}")
+    for column in columns[:8]:
+        column_type = getattr(column, "type_", getattr(column, "type", "unknown"))
+        print(f"    - {column.name}: {column_type}")
+
+    if row_count is None:
+        raise ValueError(f"Refresh for '{dataset.name}' did not report row_count")
+    if not columns:
+        raise ValueError(f"Refresh for '{dataset.name}' did not produce a schema")
+
+
+def main() -> None:
+    entities = parse_entities()
+    client = ConvexityClient()
+    try:
+        print(f"Connected to {client.base_url}")
+        project_id = find_project_id(client)
+
+        connection = find_quickbooks_connection(client, project_id)
+        if connection is None:
+            print("QuickBooks connection is not available for this project.", file=sys.stderr)
+            print("Run 001_check_quickbook_connection.py after creating the connection manually.", file=sys.stderr)
+            sys.exit(1)
+
+        connection_id = connection.get("id")
+        if not isinstance(connection_id, str) or not connection_id:
+            print(f"QuickBooks connection '{connection.get('name')}' has no connection ID.", file=sys.stderr)
+            sys.exit(1)
+
+        verified = verify_quickbooks_connection(client, connection_id)
+        if verified.get("status") != "CONNECTED":
+            print("QuickBooks connection is not connected. Run 001_check_quickbook_connection.py first.", file=sys.stderr)
+            sys.exit(1)
+
+        print(f"Using QuickBooks connection: {connection.get('name')} ({connection_id})")
+        print("Entities:", ", ".join(entity.value for entity in entities))
+
+        for entity in entities:
+            print(f"\n-- {entity.value} --")
+            dataset = create_or_update_dataset(
+                client,
+                project_id=project_id,
+                connection_id=connection_id,
+                entity=entity,
+            )
+            payload = refresh_and_wait(client, dataset)
+            print_dataset_sanity(client, dataset, payload)
+
+        print("\nDone!")
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    main()

convexity_sdk-0.12.0.dev239/samples/shopify/001_check_shopify_connection.py

@@ -0,0 +1,133 @@
+"""
+Convexity SDK - Check Shopify Connection
+
+This sample verifies that a Shopify connection exists for a project and can
+connect successfully. Run this before creating Shopify-backed datasets.
+
+Prerequisites:
+- A valid API key with READ permission for listing connections.
+- WRITE or ADMIN permission if you want the sample to run the live verify step.
+- An existing organization and project.
+  Run ../create_org_and_project.py first if needed.
+- A Shopify connection created manually in Convexity.
+
+Optional environment variables:
+- SHOPIFY_ORG_SLUG: organization slug, defaults to convexity-sdk-samples
+- SHOPIFY_PROJECT_SLUG: project slug, defaults to griffin-it
+- SHOPIFY_CONNECTION_NAME: when set, require this exact connection name
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+from convexity_sdk import ConvexityClient
+from convexity_sdk.exceptions import ConvexityError
+
+ORG_SLUG = os.getenv("SHOPIFY_ORG_SLUG", "convexity-sdk-samples")
+PROJECT_SLUG = os.getenv("SHOPIFY_PROJECT_SLUG", "griffin-it")
+SHOPIFY_CONNECTION_NAME = os.getenv("SHOPIFY_CONNECTION_NAME")
+
+
+def find_project_id(client: ConvexityClient) -> str:
+    org = client.organizations.get_by_slug(ORG_SLUG)
+    if org is None:
+        print(f"Organization '{ORG_SLUG}' not found. Run ../create_org_and_project.py first.", file=sys.stderr)
+        sys.exit(1)
+
+    project = client.projects.get_by_slug(org.id, PROJECT_SLUG)
+    if project is None:
+        print(f"Project '{PROJECT_SLUG}' not found in organization '{ORG_SLUG}'.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Using project: {project.name} ({project.id})")
+    return project.id
+
+
+def connection_to_dict(connection: Any) -> dict[str, Any]:
+    if hasattr(connection, "to_dict"):
+        data = connection.to_dict()
+        if isinstance(data, dict):
+            return data
+    return {}
+
+
+def find_shopify_connection(client: ConvexityClient, project_id: str) -> dict[str, Any] | None:
+    connections = client.connections.list(project_id=project_id).connections
+    shopify_connections = [connection_to_dict(connection) for connection in connections if connection_to_dict(connection).get("type") == "SHOPIFY"]
+
+    if SHOPIFY_CONNECTION_NAME is not None:
+        return next((connection for connection in shopify_connections if connection.get("name") == SHOPIFY_CONNECTION_NAME), None)
+
+    return shopify_connections[0] if shopify_connections else None
+
+
+def ask_user_to_create_connection(project_id: str) -> None:
+    print("Shopify connection is not available for this project.", file=sys.stderr)
+    print("Please create and connect a Shopify connection manually in Convexity, then rerun this sample.", file=sys.stderr)
+    print(f"Project ID: {project_id}", file=sys.stderr)
+    if SHOPIFY_CONNECTION_NAME is not None:
+        print(f"Expected connection name: {SHOPIFY_CONNECTION_NAME}", file=sys.stderr)
+
+
+def verify_shopify_connection(client: ConvexityClient, connection_id: str) -> dict[str, Any]:
+    response = client._http.request("post", f"/v1/connections/shopify/{connection_id}/verify")
+    data = response.json()
+    if not isinstance(data, dict):
+        raise ValueError(f"Unexpected Shopify verify response: {data!r}")
+    return data
+
+
+def main() -> None:
+    client = ConvexityClient()
+    try:
+        print(f"Connected to {client.base_url}")
+        project_id = find_project_id(client)
+
+        connection = find_shopify_connection(client, project_id)
+        if connection is None:
+            ask_user_to_create_connection(project_id)
+            sys.exit(1)
+
+        connection_id = connection.get("id")
+        if not isinstance(connection_id, str) or not connection_id:
+            print(f"Shopify connection '{connection.get('name')}' has no connection ID.", file=sys.stderr)
+            ask_user_to_create_connection(project_id)
+            sys.exit(1)
+
+        print(f"Found Shopify connection: {connection.get('name')} ({connection_id})")
+        if connection.get("shopDomain"):
+            print(f"Shop domain: {connection['shopDomain']}")
+        if connection.get("status"):
+            print(f"Stored status: {connection['status']}")
+
+        try:
+            verified = verify_shopify_connection(client, connection_id)
+        except ConvexityError as exc:
+            print(f"Shopify verification failed: {exc}", file=sys.stderr)
+            print("Please reconnect or recreate the Shopify connection manually in Convexity, then rerun this sample.", file=sys.stderr)
+            sys.exit(1)
+
+        status = verified.get("status")
+        if status != "CONNECTED":
+            print(f"Shopify connection is not connected. Current status: {status or 'unknown'}", file=sys.stderr)
+            if verified.get("errorMessage"):
+                print(f"Error: {verified['errorMessage']}", file=sys.stderr)
+            print("Please reconnect or recreate the Shopify connection manually in Convexity, then rerun this sample.", file=sys.stderr)
+            sys.exit(1)
+
+        print("Shopify connection is available and connected.")
+        if verified.get("shopName"):
+            print(f"Shop name: {verified['shopName']}")
+        if verified.get("grantedScopes"):
+            print("Granted scopes:")
+            for scope in verified["grantedScopes"]:
+                print(f"  - {scope}")
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    main()

convexity_sdk-0.12.0.dev239/samples/shopify/002_create_shopify_datasets.py

@@ -0,0 +1,262 @@
+"""
+Convexity SDK - Create Shopify Datasets
+
+This sample creates Shopify-backed datasets from an existing Shopify connection,
+refreshes them, and prints a small sanity check for row count and schema.
+
+Prerequisites:
+- Run 001_check_shopify_connection.py first.
+- A valid API key with WRITE or ADMIN permission.
+- A connected Shopify connection in the target project.
+
+Optional environment variables:
+- SHOPIFY_ORG_SLUG: organization slug, defaults to convexity-sdk-samples
+- SHOPIFY_PROJECT_SLUG: project slug, defaults to griffin-it
+- SHOPIFY_CONNECTION_NAME: when set, require this exact connection name
+- SHOPIFY_DATASET_ENTITIES: comma-separated Shopify entities, defaults to all supported entities
+- SHOPIFY_REFRESH_TIMEOUT_SECONDS: refresh timeout per dataset, defaults to 180
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from typing import Any
+
+from convexity_api_client.errors import UnexpectedStatus
+from convexity_api_client.models.dataset_config import DatasetConfig
+from convexity_api_client.models.dataset_definition import DatasetDefinition
+from convexity_api_client.models.dataset_type import DatasetType
+from convexity_api_client.models.refresh_dataset_payload import RefreshDatasetPayload
+from convexity_api_client.models.refresh_mode import RefreshMode
+from convexity_api_client.models.shopify_dataset_config import ShopifyDatasetConfig
+from convexity_api_client.models.shopify_entity import ShopifyEntity
+from convexity_api_client.models.worker_task_status import WorkerTaskStatus
+from convexity_api_client.types import Unset
+
+from convexity_sdk import ConvexityClient
+from convexity_sdk.exceptions import ConvexityError
+
+ORG_SLUG = os.getenv("SHOPIFY_ORG_SLUG", "convexity-sdk-samples")
+PROJECT_SLUG = os.getenv("SHOPIFY_PROJECT_SLUG", "griffin-it")
+SHOPIFY_CONNECTION_NAME = os.getenv("SHOPIFY_CONNECTION_NAME")
+DEFAULT_SHOPIFY_DATASET_ENTITIES = ",".join(entity.value for entity in ShopifyEntity)
+SHOPIFY_DATASET_ENTITIES = os.getenv("SHOPIFY_DATASET_ENTITIES", DEFAULT_SHOPIFY_DATASET_ENTITIES)
+REFRESH_TIMEOUT_SECONDS = int(os.getenv("SHOPIFY_REFRESH_TIMEOUT_SECONDS", "180"))
+POLL_INTERVAL_SECONDS = 5
+
+
+def parse_entities() -> list[ShopifyEntity]:
+    entities: list[ShopifyEntity] = []
+    for raw_entity in SHOPIFY_DATASET_ENTITIES.split(","):
+        entity_name = raw_entity.strip()
+        if not entity_name:
+            continue
+        try:
+            entities.append(ShopifyEntity(entity_name))
+        except ValueError:
+            valid = ", ".join(entity.value for entity in ShopifyEntity)
+            print(f"Unknown Shopify entity '{entity_name}'. Valid values: {valid}", file=sys.stderr)
+            sys.exit(1)
+    if not entities:
+        print("SHOPIFY_DATASET_ENTITIES did not include any entities.", file=sys.stderr)
+        sys.exit(1)
+    return entities
+
+
+def find_project_id(client: ConvexityClient) -> str:
+    org = client.organizations.get_by_slug(ORG_SLUG)
+    if org is None:
+        print(f"Organization '{ORG_SLUG}' not found. Run ../create_org_and_project.py first.", file=sys.stderr)
+        sys.exit(1)
+
+    project = client.projects.get_by_slug(org.id, PROJECT_SLUG)
+    if project is None:
+        print(f"Project '{PROJECT_SLUG}' not found in organization '{ORG_SLUG}'.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Using project: {project.name} ({project.id})")
+    return project.id
+
+
+def connection_to_dict(connection: Any) -> dict[str, Any]:
+    if hasattr(connection, "to_dict"):
+        data = connection.to_dict()
+        if isinstance(data, dict):
+            return data
+    return {}
+
+
+def find_shopify_connection(client: ConvexityClient, project_id: str) -> dict[str, Any] | None:
+    connections = client.connections.list(project_id=project_id).connections
+    shopify_connections = []
+    for connection in connections:
+        data = connection_to_dict(connection)
+        if data.get("type") == "SHOPIFY":
+            shopify_connections.append(data)
+
+    if SHOPIFY_CONNECTION_NAME is not None:
+        return next((connection for connection in shopify_connections if connection.get("name") == SHOPIFY_CONNECTION_NAME), None)
+
+    return shopify_connections[0] if shopify_connections else None
+
+
+def verify_shopify_connection(client: ConvexityClient, connection_id: str) -> dict[str, Any]:
+    response = client._http.request("post", f"/v1/connections/shopify/{connection_id}/verify")
+    data = response.json()
+    if not isinstance(data, dict):
+        raise ValueError(f"Unexpected Shopify verify response: {data!r}")
+    return data
+
+
+def dataset_name_for(entity: ShopifyEntity) -> str:
+    return f"shopify_{entity.value.lower()}"
+
+
+def build_config(entity: ShopifyEntity) -> DatasetConfig:
+    return DatasetConfig(shopify=ShopifyDatasetConfig(entity=entity))
+
+
+def find_existing_dataset(client: ConvexityClient, project_id: str, name: str) -> DatasetDefinition | None:
+    datasets = client.datasets.list(project_id).datasets
+    return next((dataset for dataset in datasets if dataset.name == name), None)
+
+
+def create_or_update_dataset(
+    client: ConvexityClient,
+    *,
+    project_id: str,
+    connection_id: str,
+    entity: ShopifyEntity,
+) -> DatasetDefinition:
+    name = dataset_name_for(entity)
+    config = build_config(entity)
+    existing = find_existing_dataset(client, project_id, name)
+    if existing is not None:
+        dataset = client.datasets.update(
+            existing.id,
+            connection_id=connection_id,
+            config=config,
+            refresh_mode=RefreshMode.MANUAL,
+        )
+        print(f"Updated dataset: {dataset.name} ({dataset.id})")
+        return dataset
+
+    dataset = client.datasets.create(
+        project_id=project_id,
+        name=name,
+        type_=DatasetType.SHOPIFY,
+        config=config,
+        connection_id=connection_id,
+        refresh_mode=RefreshMode.MANUAL,
+        description=f"Shopify {entity.value} dataset created by the SDK sample",
+        tags=["shopify", "sdk-sample"],
+    )
+    print(f"Created dataset: {dataset.name} ({dataset.id})")
+    return dataset
+
+
+def refresh_and_wait(client: ConvexityClient, dataset: DatasetDefinition) -> RefreshDatasetPayload:
+    try:
+        task = client.datasets.refresh(dataset.id)
+    except (UnexpectedStatus, ConvexityError, ValueError) as exc:
+        raise RuntimeError(f"Failed to trigger refresh for '{dataset.name}': {exc}") from exc
+
+    print(f"  Refresh started (task_id={task.id})", end="", flush=True)
+    deadline = time.monotonic() + REFRESH_TIMEOUT_SECONDS
+    while True:
+        if time.monotonic() > deadline:
+            raise TimeoutError(f"Refresh timed out for '{dataset.name}' after {REFRESH_TIMEOUT_SECONDS} seconds")
+
+        time.sleep(POLL_INTERVAL_SECONDS)
+        state = client.datasets.get_refresh_status(dataset.id, task.id)
+        payload = state.payload
+        if isinstance(payload, RefreshDatasetPayload):
+            message = payload.progress_message if not isinstance(payload.progress_message, Unset) else None
+            if message:
+                print(f" {message}", end="", flush=True)
+        else:
+            payload = None
+
+        if state.status == WorkerTaskStatus.COMPLETED:
+            print(" COMPLETED")
+            if payload is None:
+                raise ValueError(f"Refresh completed for '{dataset.name}' without a refresh payload")
+            return payload
+
+        if state.status == WorkerTaskStatus.FAILED:
+            error = state.error if not isinstance(state.error, Unset) else "unknown error"
+            raise RuntimeError(f"Refresh failed for '{dataset.name}': {error}")
+
+        if state.status == WorkerTaskStatus.CANCELLED:
+            raise RuntimeError(f"Refresh was cancelled for '{dataset.name}'")
+
+        print(".", end="", flush=True)
+
+
+def print_dataset_sanity(client: ConvexityClient, dataset: DatasetDefinition, payload: RefreshDatasetPayload) -> None:
+    refreshed = client.datasets.get(dataset.id)
+    if refreshed is None:
+        raise ValueError(f"Could not fetch refreshed dataset '{dataset.name}'")
+
+    row_count = payload.row_count if not isinstance(payload.row_count, Unset) else None
+    schema = refreshed.schema
+    columns = [] if schema is None or isinstance(schema, Unset) else schema
+
+    print(f"  Rows written: {row_count if row_count is not None else 'unknown'}")
+    print(f"  Columns: {len(columns)}")
+    for column in columns[:8]:
+        column_type = getattr(column, "type_", getattr(column, "type", "unknown"))
+        print(f"    - {column.name}: {column_type}")
+
+    if row_count is None:
+        raise ValueError(f"Refresh for '{dataset.name}' did not report row_count")
+    if not columns:
+        raise ValueError(f"Refresh for '{dataset.name}' did not produce a schema")
+
+
+def main() -> None:
+    entities = parse_entities()
+    client = ConvexityClient()
+    try:
+        print(f"Connected to {client.base_url}")
+        project_id = find_project_id(client)
+
+        connection = find_shopify_connection(client, project_id)
+        if connection is None:
+            print("Shopify connection is not available for this project.", file=sys.stderr)
+            print("Run 001_check_shopify_connection.py after creating the connection manually.", file=sys.stderr)
+            sys.exit(1)
+
+        connection_id = connection.get("id")
+        if not isinstance(connection_id, str) or not connection_id:
+            print(f"Shopify connection '{connection.get('name')}' has no connection ID.", file=sys.stderr)
+            sys.exit(1)
+
+        verified = verify_shopify_connection(client, connection_id)
+        if verified.get("status") != "CONNECTED":
+            print("Shopify connection is not connected. Run 001_check_shopify_connection.py first.", file=sys.stderr)
+            sys.exit(1)
+
+        print(f"Using Shopify connection: {connection.get('name')} ({connection_id})")
+        print("Entities:", ", ".join(entity.value for entity in entities))
+
+        for entity in entities:
+            print(f"\n-- {entity.value} --")
+            dataset = create_or_update_dataset(
+                client,
+                project_id=project_id,
+                connection_id=connection_id,
+                entity=entity,
+            )
+            payload = refresh_and_wait(client, dataset)
+            print_dataset_sanity(client, dataset, payload)
+
+        print("\nDone!")
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    main()

convexity_sdk-0.12.0.dev237/samples/README.md

@@ -1,27 +0,0 @@
-git pull# Convexity SDK Samples
-
-This directory contains sample scripts demonstrating how to use the Convexity SDK.
-
-## Samples
-
-| Sample                                                               | Description                                 |
-| -------------------------------------------------------------------- | ------------------------------------------- |
-| [getting_started.py](getting_started.py)                             | Basic SDK setup and usage                   |
-| [create_org_and_project.py](create_org_and_project.py)               | Create an organization and project          |
-| [create_databricks_connections.py](create_databricks_connections.py) | Create Databricks connections               |
-| [create_datasets.py](create_datasets.py)                             | Create datasets from Databricks connections |
-| [create_dashboards.py](create_dashboards.py)                         | Create analytic dashboards with widgets     |
-| [share_dashboard.py](share_dashboard.py)                             | Share a dashboard with other users          |
-| [list_orgs_and_projects.py](list_orgs_and_projects.py)               | List organizations and projects             |
-| [query_datalake.py](query_datalake.py)                               | Query the DuckLake warehouse with DuckDB    |
-| [cancel_refresh_task.py](cancel_refresh_task.py)                     | Cancel a pending dataset refresh task       |
-| [create_forecast_task.py](create_forecast_task.py)                   | Create a demand-forecasting task and run it |
-| [compare_api_key_scopes.py](compare_api_key_scopes.py)               | Compare READ vs ADMIN API key behavior      |
-| [debug_api_key_tenant_context.py](debug_api_key_tenant_context.py)   | Diagnose API key tenant/scope mismatch      |
-
-## Running Samples
-
-```bash
-# From the repo root
-uv run python packages/convexity-sdk/samples/getting_started.py
-```

convexity_sdk-0.12.0.dev237/samples/create_org_and_project.py

@@ -1,51 +0,0 @@
-"""
-Convexity SDK - Create Organization & Project
-
-This sample demonstrates how to:
-- Create a new organization
-- Add members to the organization as admins
-- Create a project within the organization
-
-Prerequisites:
-- A valid API key with WRITE or ADMIN permission
-"""
-
-from convexity_api_client.models.organization_role import OrganizationRole
-
-from convexity_sdk import ConvexityClient
-
-client = ConvexityClient()
-
-# ── Step 1: Create a new organization ───────────────────────────────────
-org = client.organizations.create(
-    name="Convexity SDK samples",
-    slug="convexity-sdk-samples",
-    description="Organization created by the Convexity SDK sample scripts",
-)
-print(f"Created organization: {org.name} (id={org.id})")
-
-# ── Step 2: Add admin members ──────────────────────────────────────────
-admin_user_ids = [
-    "6eadd2f4-08aa-4017-9131-6ba87d066b12",
-    "c572deb6-8c2e-4515-a23e-fb468a721048",
-]
-
-for user_id in admin_user_ids:
-    member = client.organizations.add_member(
-        org.id,
-        user_id=user_id,
-        role=OrganizationRole.ADMIN,
-    )
-    print(f"  Added admin: {member.user_id} (role={member.role})")
-
-# ── Step 3: Create a project in the organization ───────────────────────
-project = client.projects.create(
-    name="griffin it",
-    slug="griffin-it",
-    organization_id=org.id,
-    description="Test project created by the Convexity SDK sample scripts",
-)
-print(f"Created project: {project.name} (id={project.id})")
-
-print("\nDone!")
-client.close()