flowstash-cli 0.1.3__tar.gz → 0.2.0__tar.gz

{flowstash_cli-0.1.3 → flowstash_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flowstash-cli
-Version: 0.1.3
+Version: 0.2.0
 Summary: CLI for the flowstash Managed Platform
 Author: juraj.bezdek@gmail.com
 Author-email: juraj.bezdek@gmail.com

{flowstash_cli-0.1.3 → flowstash_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flowstash-cli"
-version = "0.1.3"
+version = "0.2.0"
 description = "CLI for the flowstash Managed Platform"
 authors = [{name = "juraj.bezdek@gmail.com", email = "juraj.bezdek@gmail.com"}]
 requires-python = ">=3.11"
@@ -18,11 +18,11 @@ dependencies = [
 ]
 
 [project.scripts]
-flowstash = "flowstash.main:app"
+flowstash = "flowstash.cli.main:app"
 
 [tool.poetry]
 packages = [
-    { include = "flowstash" }
+    { include = "flowstash", from = "src" }
 ]
 
 [tool.poetry.dependencies]

{flowstash_cli-0.1.3/flowstash → flowstash_cli-0.2.0/src/flowstash/cli}/commands/webhook.py

@@ -60,7 +60,7 @@ except Exception as e:
     print(json.dumps({{"error": str(e)}}))
     sys.exit(1)
 
-from flowstash_lib.pipelines.ingress import ingress
+from flowstash.ingress import ingress
 result = []
 for h in ingress.get_webhooks():
     m = h._ingress_metadata

{flowstash_cli-0.1.3/flowstash → flowstash_cli-0.2.0/src/flowstash/cli}/main.py

@@ -43,6 +43,7 @@ app.add_typer(env_app, name="env")
 app.add_typer(
     webhook_cmds.app,
     name="webhook",
+    help="Start a temporary public webhook listener to capture sample payloads",
     no_args_is_help=True,
 )
 

{flowstash_cli-0.1.3/flowstash → flowstash_cli-0.2.0/src/flowstash/cli}/templates/AGENTS.md

@@ -13,13 +13,13 @@ flowstash integrations revolve around the following core ideas:
 
 ## Bringing Data In: Ingress
 
-You can trigger your pipelines through two main ingress decorators provided by `flowstash_lib.pipelines.ingress`:
+You can trigger your pipelines through two main ingress decorators provided by `flowstash.ingress`:
 
 ### 1. Webhooks (`@ingress.webhook`)
 Use webhooks when an external system can push events to your application. This decorator registers the handler as part of the integration but leaves the exact handling logic to you.
 
 ```python
-from flowstash_lib.pipelines.ingress import ingress
+from flowstash.ingress import ingress
 
 @router.post("/webhook/slack")
 @ingress.webhook(pipeline="slack.messages", integration="slack")
@@ -34,7 +34,7 @@ Use polling when you need to fetch data on a schedule. This decorator acts as a
 The state is automatically saved for you as long as the function executes without exceptions.
 
 ```python
-from flowstash_lib.pipelines.ingress import ingress
+from flowstash.ingress import ingress
 from datetime import datetime
 
 @ingress.poll(pipeline="slack.messages", integration="slack", schedule="*/5 * * * *")
@@ -51,6 +51,64 @@ async def poll_slack(state: dict):
     state["since"] = datetime.now()
 ```
 
+## State Management: The State Machine Principle
+
+Integrations often need to remember things between runs. flowstash treats every integration run as a transition in a **state machine**. You load the current state, perform your logic, and save the updated state.
+
+### The `State` Facade
+
+The `State` facade (accessible via `from flowstash.integration import State`) provides a centralized interface for persistent storage. It automatically handles namespacing, serialization, and TTLs, so you can focus on the data.
+
+#### Scopes
+State is automatically isolated into three logical scopes based on the active context:
+- **`integration` (Default)**: Shared across all tasks and pipelines in a specific integration (e.g., `slack`). Use for global settings or cross-pipeline flags.
+- **`pipeline`**: Shared across all tasks in a specific pipeline (e.g., `slack.sync_users`).
+- **`ingress`**: Private state for a specific ingress entrypoint (e.g., a specific poll timer). This is the default scope for the `state` dict injected into `@ingress.poll`.
+
+#### Basic Usage
+```python
+from flowstash.integration import State
+
+@integration_task(integration="demo", pipeline="example")
+async def my_stateful_task():
+    # 1. Get current state (scoped to integration:demo by default)
+    # Returns None or the decoded value (JSON objects are automatically parsed)
+    last_processed = State.get("last_id") or 0
+    
+    # ... perform logic ...
+    
+    # 2. Update state (persists to the configured backend: Redis, SQLite, Managed, etc.)
+    State.set("last_id", 123)
+```
+
+### Auto-Saving in Ingress
+In `@ingress.poll`, state management is handled for you. The `state` dictionary is automatically loaded before your function runs and persisted back to the `ingress` scope precisely when your function returns successfully.
+
+```python
+@ingress.poll(pipeline="demo", integration="acme", schedule="* * * * *")
+async def poll_handler(state: dict):
+    # This 'state' is already loaded for you
+    cursor = state.get("cursor", "init")
+    
+    # ... fetching data ...
+    
+    # Changes to this dict are automatically saved on a successful return
+    state["cursor"] = "next_page_token"
+```
+
+### Context Bound
+`State` is fully context-aware. You don't need to pass around tenant IDs or integration names. When you are inside an `@integration_task`, `@integration_step` or an `@ingress` handler, `State` already knows where to store the data.
+
+If you need to use `State` in a CLI script or a test outside of a managed run, you can bind it manually:
+```python
+from flowstash.context import integration_context
+
+with integration_context(integration="my-int", integration_pipeline="pipe"):
+    # Inside this block, State is bound to "my-int" and "pipe"
+    State.set("setup_complete", True)
+```
+
+
 ## Making External Requests: Clients
 
 flowstash makes it easy to interact with external APIs via Clients. They handle setting Base URLs, automatic Authentication headers, observability tracing, and defaults out of the box.
@@ -64,11 +122,11 @@ pattern: "*.yaml"
 You can simply define `clients/slackClient.yaml` and the system will expose it to your tasks.
 
 ### Using a Client
-Once configured, you can retrieve the standard HTTP client (from the `flowstash_clients` package) anywhere.
+Once configured, you can retrieve the standard HTTP client (from the `flowstash.clients` package) anywhere.
 
 ```python
-from flowstash_clients import get_client
-from flowstash_lib.decorators import integration_task
+from flowstash.clients import get_client
+from flowstash.decorators import integration_task
 
 # Load the client configuration
 slack_client = get_client("slackClient")
@@ -83,7 +141,7 @@ async def send_slack_message_task(message: str):
 If you have an API you interact with heavily, you can define a custom typed client. This encapsulates specific API routes for a better developer experience.
 
 ```python
-from flowstash_lib.clients import HttpClient, client
+from flowstash.clients import HttpClient, client
 from typing import List
 
 # Extending HttpClient and registering with the @client decorator
@@ -113,8 +171,8 @@ The framework resolves deduplication using a unique combination of `(integration
 It also seamlessly supports feeding massive data payloads -- large objects (> 5KB) are automatically offloaded to a BlobStore.
 
 ```python
-from flowstash_lib.pipelines.records_feed import RecordsFeed
-from flowstash_lib.pipelines.records_model import RecordData
+from flowstash.pipelines.records_feed import RecordsFeed
+from flowstash.pipelines.records_model import RecordData
 
 # Retrieve your specific feed
 feed = RecordsFeed.get(feed_id="slack.messages")
@@ -131,7 +189,7 @@ await feed.publish(RecordData(
 To process the data asynchronously, decorate a function with `@feed_consumer`. This supports robust configurations like automatic batched receiving, delays, rate-limiting, and concurrency control.
 
 ```python
-from flowstash_lib import feed_consumer, RecordData
+from flowstash.pipelines import feed_consumer, RecordData
 
 @feed_consumer(
     feed_id="slack.messages", 

{flowstash_cli-0.1.3/flowstash → flowstash_cli-0.2.0/src/flowstash/cli}/templates/README.md

@@ -90,7 +90,7 @@ python worker.py
 
 ## flowstash Core Concepts Usage
 
-This project is built on `flowstash_lib` – a core library providing robust context management, queue abstractions, and observability. Here is how you can utilize its components in your application:
+This project is built on `flowstash` – a core library providing robust context management, queue abstractions, and observability. Here is how you can utilize its components in your application:
 
 ### Integration Context
 `IntegrationContext` propagates automatically through all your integration operations. It manages the current `run_id`, `integration`, and `current_record_key` to ensure all logs and traces are correctly correlated without manual passing.
@@ -102,7 +102,7 @@ This project is built on `flowstash_lib` – a core library providing robust con
 ### RecordsFeed & Consumers
 Extract and ingest data efficiently using **RecordsFeed**:
 ```python
-from flowstash_lib.pipelines.records_feed import RecordsFeed, RecordData
+from flowstash.pipelines.records_feed import RecordsFeed, RecordData
 
 feed = RecordsFeed.get(feed_id="your.pipeline")
 feed.publish(RecordData(record_id="123", record_type="invoice", data={...}))
@@ -111,7 +111,7 @@ Records are automatically deduplicated and optionally ordered by timestamp.
 
 Consume them robustly with **Feed Consumers**, which handle batching, rate-limiting, and parallel execution automatically:
 ```python
-from flowstash_lib.pipelines.consumer import feed_consumer
+from flowstash.pipelines.consumer import feed_consumer
 
 @feed_consumer(
   feed_id="your.pipeline",
@@ -129,7 +129,7 @@ async def process_records(records: list[RecordData]):
 Use the provided `logger` to naturally correlate your logs with the active context. The framework tracks the lifecycle of records intrinsically (from publishing to consumption) without manual `record_id` logging.
 
 ```python
-from flowstash_lib import logger
+from flowstash.observability.logging import logger
 
 logger.info("Processing the invoice batch", details="step 1 completed")
 ```

{flowstash_cli-0.1.3/flowstash → flowstash_cli-0.2.0/src/flowstash/cli}/templates/_api_main.py

@@ -1,7 +1,7 @@
 from pathlib import Path
 from fastapi import Request
-from flowstash_lib.config.env_loader import load_config_dir
-from flowstash_runtime.ingress.app import create_fastapi_app
+from flowstash.config.env_loader import load_config_dir
+from flowstash.runtime.ingress.app import create_fastapi_app
 import os
 env = os.getenv("ENVIRONMENT", "dev")
 # Load configuration relative to this file

{flowstash_cli-0.1.3/flowstash → flowstash_cli-0.2.0/src/flowstash/cli}/templates/_src/_api/_routes/webhooks.py

@@ -1,7 +1,7 @@
-from flowstash_lib import ingress
-from flowstash_lib import RecordData
+from flowstash import ingress
+from flowstash.pipelines import RecordData
 from fastapi import Request
-from flowstash_lib.pipelines.records_feed import RecordsFeed
+from flowstash.pipelines.records_feed import RecordsFeed
 
 @ingress.webhook(integration="demo", pipeline="process_user", path="/demo/process_user", method="POST")
 async def process_user_webhook(request: Request):

{flowstash_cli-0.1.3/flowstash → flowstash_cli-0.2.0/src/flowstash/cli}/templates/_src/_shared/clients/client.py

@@ -1,5 +1,5 @@
 from typing import List, Optional
-from flowstash_lib.clients import HttpClient, client
+from flowstash.clients import HttpClient, client
 
 @client("DemoClient")
 class DemoClient(HttpClient):

{flowstash_cli-0.1.3/flowstash → flowstash_cli-0.2.0/src/flowstash/cli}/templates/_src/_shared/tasks/sharedTasks.py

@@ -1,5 +1,5 @@
-from flowstash_lib.decorators import integration_task
-from flowstash_clients import get_client
+from flowstash.decorators import integration_task
+from flowstash.clients import get_client
 
 @integration_task(integration="demo", integration_pipeline="adhoc_task")
 async def adhoc_task(data: dict):

{flowstash_cli-0.1.3/flowstash → flowstash_cli-0.2.0/src/flowstash/cli}/templates/_src/_worker/tasks/tasks.py

@@ -1,5 +1,5 @@
-from flowstash_lib.decorators import integration_task
-from flowstash_lib.queue.backend import Schedule
+from flowstash.decorators import integration_task
+from flowstash.queue.backend import Schedule
 
 
 

{flowstash_cli-0.1.3/flowstash → flowstash_cli-0.2.0/src/flowstash/cli}/templates/_worker_main.py

@@ -2,8 +2,8 @@ import os
 import asyncio
 import logging
 from pathlib import Path
-from flowstash_lib.config.env_loader import load_config_dir
-from flowstash_runtime import initialize_runtime, run_worker
+from flowstash.config.env_loader import load_config_dir
+from flowstash.runtime import initialize_runtime, run_worker
 
 logging.basicConfig(level=logging.INFO)