paypal-agent-toolkit 1.0.0__tar.gz

paypal_agent_toolkit-1.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: paypal-agent-toolkit
+Version: 1.0.0
+Summary: A toolkit for agent interactions with PayPal API.
+Author-email: PayPal <support@paypal.com>
+Project-URL: Bug Tracker, https://github.com/paypal/agent-toolkit/issues
+Project-URL: Source Code, https://github.com/paypal/agent-toolkit
+Keywords: paypal,payments,checkout,api
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pydantic>=2.10
+
+# PayPal Agentic Toolkit
+
+The PayPal Agentic Toolkit integrates PayPal's REST APIs seamlessly with OpenAI Agents, allowing AI-driven management of PayPal transactions.
+
+## Available tools
+
+The PayPal Agent toolkit provides the following tools:
+
+**Orders**
+
+- `create_order`: Create an order in PayPal system based on provided details
+- `get_order`: Retrieve the details of an order
+- `capture_order`: Capture payment for an authorized order
+
+**Products**
+
+- `create_product`: Create a new product in the PayPal catalog
+- `list_products`: List products with optional pagination and filtering
+- `show_product_details`: Retrieve details of a specific product
+- `update_product`: Update an existing product
+
+**Subscription Plans**
+
+- `create_subscription_plan`: Create a new subscription plan
+- `list_subscription_plans`: List subscription plans
+- `show_subscription_plan_details`: Retrieve details of a specific subscription plan
+
+**Subscriptions**
+
+- `create_subscription`: Create a new subscription
+- `show_subscription_details`: Retrieve details of a specific subscription
+- `cancel_subscription`: Cancel an active subscription
+
+
+## Prerequisites
+
+Before setting up the workspace, ensure you have the following installed:
+- Python 3.11 or higher
+- `pip` (Python package manager)
+- A PayPal developer account for API credentials
+
+## Installation
+
+You don't need this source code unless you want to modify the package. If you just
+want to use the package, just run:
+
+```sh
+pip install paypal-agent-toolkit
+```
+
+## Usage
+
+The library needs to be configured with your PayPal developer account's API credentials which is
+available in your [PayPal Developer Dashboard][app-keys].
+
+```python
+from paypal_agent_toolkit.openai.toolkit import PayPalToolkit
+from paypal_agent_toolkit.common.configuration import Configuration, Context
+
+configuration = Configuration(
+    actions={
+        "orders": {
+            "create": True,
+            "get": True,
+            "capture": True,
+        }
+    },
+    context=Context(
+        sandbox=True
+    )
+)
+
+# Initialize toolkit
+toolkit = PayPalToolkit(client_id=PAYPAL_CLIENT_ID, secret=PAYPAL_SECRET, configuration = configuration)
+
+```
+
+This toolkit is designed to work with OpenAI's Agent SDK and Assistant API. It provides pre-built tools for managing PayPal transactions like creating, capturing, and checking orders details etc.
+
+
+### Using with OpenAI Agent SDK
+```python
+from agents import Agent
+
+tools = toolkit.get_tools()
+
+agent = Agent(
+    name="PayPal Assistant",
+    instructions="""
+    You're a helpful assistant specialized in managing PayPal transactions:
+    - To create orders, invoke create_order.
+    - After approval by user, invoke capture_order.
+    - To check an order status, invoke get_order_status.
+    """,
+    tools=tools
+)
+```
+
+
+### Using with OpenAI Assistants API
+```python
+
+tools = toolkit.get_openai_chat_tools()
+paypal_api = toolkit.get_paypal_api()
+
+# Create assistant
+assistant = client.beta.assistants.create(
+    name="PayPal Checkout Assistant",
+    instructions=f"""
+You help users create and capture PayPal orders. When the user wants to make a purchase,
+use the create_order tool and share the approval link. After approval, use capture_order.
+""",
+    model="gpt-4-1106-preview",
+    tools=tools
+)
+
+# Create thread
+thread = client.beta.threads.create()
+
+# Start or retrieve a run
+run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
+```
+
+Examples for OpenAI's Agent SDK are included in [/examples](/examples).
+
+[app-keys]: https://developer.paypal.com/dashboard/applications/sandbox
+
+## Disclaimer
+AI-generated content may be inaccurate or incomplete. Users are responsible for independently verifying any information before relying on it. PayPal makes no guarantees regarding output accuracy and is not liable for any decisions, actions, or consequences resulting from its use.

paypal_agent_toolkit-1.0.0/README.md

@@ -0,0 +1,129 @@
+# PayPal Agentic Toolkit
+
+The PayPal Agentic Toolkit integrates PayPal's REST APIs seamlessly with OpenAI Agents, allowing AI-driven management of PayPal transactions.
+
+## Available tools
+
+The PayPal Agent toolkit provides the following tools:
+
+**Orders**
+
+- `create_order`: Create an order in PayPal system based on provided details
+- `get_order`: Retrieve the details of an order
+- `capture_order`: Capture payment for an authorized order
+
+**Products**
+
+- `create_product`: Create a new product in the PayPal catalog
+- `list_products`: List products with optional pagination and filtering
+- `show_product_details`: Retrieve details of a specific product
+- `update_product`: Update an existing product
+
+**Subscription Plans**
+
+- `create_subscription_plan`: Create a new subscription plan
+- `list_subscription_plans`: List subscription plans
+- `show_subscription_plan_details`: Retrieve details of a specific subscription plan
+
+**Subscriptions**
+
+- `create_subscription`: Create a new subscription
+- `show_subscription_details`: Retrieve details of a specific subscription
+- `cancel_subscription`: Cancel an active subscription
+
+
+## Prerequisites
+
+Before setting up the workspace, ensure you have the following installed:
+- Python 3.11 or higher
+- `pip` (Python package manager)
+- A PayPal developer account for API credentials
+
+## Installation
+
+You don't need this source code unless you want to modify the package. If you just
+want to use the package, just run:
+
+```sh
+pip install paypal-agent-toolkit
+```
+
+## Usage
+
+The library needs to be configured with your PayPal developer account's API credentials which is
+available in your [PayPal Developer Dashboard][app-keys].
+
+```python
+from paypal_agent_toolkit.openai.toolkit import PayPalToolkit
+from paypal_agent_toolkit.common.configuration import Configuration, Context
+
+configuration = Configuration(
+    actions={
+        "orders": {
+            "create": True,
+            "get": True,
+            "capture": True,
+        }
+    },
+    context=Context(
+        sandbox=True
+    )
+)
+
+# Initialize toolkit
+toolkit = PayPalToolkit(client_id=PAYPAL_CLIENT_ID, secret=PAYPAL_SECRET, configuration = configuration)
+
+```
+
+This toolkit is designed to work with OpenAI's Agent SDK and Assistant API. It provides pre-built tools for managing PayPal transactions like creating, capturing, and checking orders details etc.
+
+
+### Using with OpenAI Agent SDK
+```python
+from agents import Agent
+
+tools = toolkit.get_tools()
+
+agent = Agent(
+    name="PayPal Assistant",
+    instructions="""
+    You're a helpful assistant specialized in managing PayPal transactions:
+    - To create orders, invoke create_order.
+    - After approval by user, invoke capture_order.
+    - To check an order status, invoke get_order_status.
+    """,
+    tools=tools
+)
+```
+
+
+### Using with OpenAI Assistants API
+```python
+
+tools = toolkit.get_openai_chat_tools()
+paypal_api = toolkit.get_paypal_api()
+
+# Create assistant
+assistant = client.beta.assistants.create(
+    name="PayPal Checkout Assistant",
+    instructions=f"""
+You help users create and capture PayPal orders. When the user wants to make a purchase,
+use the create_order tool and share the approval link. After approval, use capture_order.
+""",
+    model="gpt-4-1106-preview",
+    tools=tools
+)
+
+# Create thread
+thread = client.beta.threads.create()
+
+# Start or retrieve a run
+run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
+```
+
+Examples for OpenAI's Agent SDK are included in [/examples](/examples).
+
+[app-keys]: https://developer.paypal.com/dashboard/applications/sandbox
+
+## Disclaimer
+AI-generated content may be inaccurate or incomplete. Users are responsible for independently verifying any information before relying on it. PayPal makes no guarantees regarding output accuracy and is not liable for any decisions, actions, or consequences resulting from its use.

paypal_agent_toolkit-1.0.0/paypal_agent_toolkit/common/api.py

@@ -0,0 +1,28 @@
+
+
+from typing import Optional
+from pydantic import BaseModel
+from .configuration import Context
+from .paypal_client import PayPalClient
+from .tools import tools
+
+class PayPalAPI(BaseModel):
+    
+    _context: Context
+    _paypal_client: PayPalClient
+    
+    def __init__(self, client_id: str, secret: str, context: Optional[Context]):
+        super().__init__()
+
+        self._context = context if context is not None else Context()
+        self._paypal_client = PayPalClient(client_id=client_id, secret=secret, context=context)
+        
+    
+    def run(self, method: str, kwargs) -> str:
+        for tool in tools:
+            if tool.get("method") == method:
+                execute_fn = tool.get("execute")
+                if execute_fn:
+                    return execute_fn(self._paypal_client, kwargs)
+        raise ValueError("create_order method not found in tools list")
+

paypal_agent_toolkit-1.0.0/paypal_agent_toolkit/common/configuration.py

@@ -0,0 +1,32 @@
+from typing import Optional, Dict, Any
+
+class Context:
+    def __init__(
+        self,
+        merchant_id: Optional[str] = None,
+        sandbox: Optional[bool] = None,
+        access_token: Optional[str] = None,
+        request_id: Optional[str] = None,
+        tenant_context: Optional[Any] = None,
+        debug: Optional[bool] = None,
+        **kwargs: Any
+    ):
+        self.merchant_id = merchant_id
+        self.sandbox = sandbox or False
+        self.access_token = access_token
+        self.request_id = request_id
+        self.tenant_context = tenant_context
+        self.debug = debug or False
+        self.extra = kwargs
+
+class Configuration:
+    def __init__(self, actions: Dict[str, Dict[str, bool]], context: Optional[Context] = None):
+        self.actions = actions
+        self.context = context
+
+def is_tool_allowed(tool: Dict[str, Dict[str, Dict[str, bool]]], configuration: Configuration) -> bool:
+    for product, product_actions in tool.get("actions", {}).items():
+        for action, allowed in product_actions.items():
+            if configuration.actions.get(product, {}).get(action, False):
+                return True
+    return False

paypal_agent_toolkit-1.0.0/paypal_agent_toolkit/common/constants.py

@@ -0,0 +1,4 @@
+SANDBOX_BASE_URL = "https://api-m.sandbox.paypal.com"
+LIVE_BASE_URL = "https://api-m.paypal.com"
+ENV_SANDBOX = "sandbox"
+ENV_LIVE = "live"

paypal_agent_toolkit-1.0.0/paypal_agent_toolkit/common/logger_util.py

@@ -0,0 +1,30 @@
+
+import logging
+import json
+
+def mask_bearer_token(token: str) -> str:
+    if not token.startswith("Bearer "):
+        return token
+    raw = token[7:]  # remove "Bearer "
+    if len(raw) <= 8:
+        return "Bearer ****"
+    return f"Bearer {raw[:4]}****{raw[-4:]}"
+
+
+def logRequestPayload(debug, payload, url, headers):
+    logging.debug("POST %s", url)
+    if debug:
+        # Mask sensitive header before logging
+        masked_headers = {
+            **headers,
+            "Authorization": mask_bearer_token(headers["Authorization"])
+        }
+        logging.debug("Request Headers:\n%s", json.dumps(masked_headers, indent=2))
+    logging.debug("Request Payload:\n%s", json.dumps(payload, indent=2))     
+
+
+def configure_logging(debug: bool):
+    logging.basicConfig(
+        level=logging.DEBUG if debug else logging.ERROR,
+        format="%(asctime)s - %(levelname)s - %(message)s"
+    )

paypal_agent_toolkit-1.0.0/paypal_agent_toolkit/common/parameters.py

@@ -0,0 +1,246 @@
+from pydantic import BaseModel, Field, HttpUrl, validator, field_validator, ConfigDict, constr
+from typing import List, Literal, Optional
+
+
+
+class ItemDetails(BaseModel):
+    item_cost: float = Field(..., description="The cost of each item – up to 2 decimal points.")
+    tax_percent: float = Field(0, description="The tax percent for the specific item.")
+    item_total: float = Field(..., description="The total cost of this line item.")
+
+
+class LineItem(ItemDetails):
+    name: str = Field(..., description="The name of the item.")
+    quantity: int = Field(
+        1,
+        description="The item quantity. Must be a whole number.",
+        ge=1
+    )
+    description: Optional[str] = Field(
+        None,
+        description="The detailed item description."
+    )
+
+
+class ShippingAddress(BaseModel):
+    address_line_1: Optional[str] = Field(
+        None,
+        description=(
+            "The first line of the address, such as number and street, "
+            "for example, `173 Drury Lane`. This field needs to pass the full address."
+        )
+    )
+    address_line_2: Optional[str] = Field(
+        None,
+        description="The second line of the address, for example, a suite or apartment number."
+    )
+    admin_area_2: Optional[str] = Field(
+        None,
+        description="A city, town, or village. Smaller than `admin_area_level_1`."
+    )
+    admin_area_1: Optional[str] = Field(
+        None,
+        description=(
+            "The highest-level sub-division in a country, which is usually a province, "
+            "state, or ISO-3166-2 subdivision."
+        )
+    )
+    postal_code: Optional[str] = Field(
+        None,
+        description=(
+            "The postal code, which is the ZIP code or equivalent. Typically required "
+            "for countries with a postal code or an equivalent."
+        )
+    )
+    country_code: Optional[constr(min_length=2, max_length=2)] = Field(
+        None,
+        description=(
+            "The 2-character ISO 3166-1 code that identifies the country or region. "
+            "Note: The country code for Great Britain is `GB`."
+        )
+    )
+
+
+class CreateOrderParameters(BaseModel):
+    model_config = ConfigDict(validate_default=True)
+    currency_code: Literal["USD"] = Field(
+        ...,
+        description="Currency code of the amount."
+    )
+    items: List[LineItem] = Field(
+        ...,
+        description="List of individual items in the order (max 50)."
+    )
+    discount: float = Field(
+        0,
+        description="The discount amount for the order."
+    )
+    shipping_cost: float = Field(
+        0,
+        description="The cost of shipping for the order."
+    )
+    shipping_address: Optional[ShippingAddress] = Field(
+        None,
+        description="The shipping address for the order."
+    )
+    notes: Optional[str] = Field(
+        None,
+        description="Optional customer notes or instructions."
+    )
+    return_url: Optional[HttpUrl] = Field(
+        "https://example.com/returnUrl",
+        description="URL to redirect the buyer after approval."
+    )
+    cancel_url: Optional[HttpUrl] = Field(
+        "https://example.com/cancelUrl",
+        description="URL to redirect the buyer if they cancel."
+    )
+
+
+class OrderIdParameters(BaseModel):
+    order_id: str
+
+class CaptureOrderParameters(BaseModel):
+    order_id: str
+    
+
+class CreateProductParameters(BaseModel):
+    name: str
+    type: Literal['PHYSICAL', 'DIGITAL', 'SERVICE']  # Enum-like behavior for product type
+    description: Optional[str] = None
+    category: Optional[str] = None
+    image_url: Optional[HttpUrl] = None  # Ensures valid URL
+    home_url: Optional[HttpUrl] = None  # Ensures valid URL
+
+class ListProductsParameters(BaseModel):
+    page: Optional[int] = None
+    page_size: Optional[int] = None
+    total_required: Optional[bool] = None
+
+class ShowProductDetailsParameters(BaseModel):
+    product_id: str
+
+# Frequency Schema
+class FrequencySchema(BaseModel):
+    interval_unit: Literal['DAY', 'WEEK', 'MONTH', 'YEAR'] = Field(..., description="The unit of time for the billing cycle.")
+    interval_count: int = Field(..., description="The number of units for the billing cycle.")
+
+# Pricing Scheme Schema
+class FixedPriceSchema(BaseModel):
+    currency_code: Literal['USD'] = Field(..., description="The currency code for the fixed price.")
+    value: str = Field(..., description="The value of the fixed price.")
+
+class PricingSchemeSchema(BaseModel):
+    fixed_price: Optional[FixedPriceSchema] = Field(None, description="The fixed price for the subscription plan.")
+    version: Optional[str] = Field(None, description="The version of the pricing scheme.")
+
+# Billing Cycle Schema
+class BillingCycleSchema(BaseModel):
+    frequency: FrequencySchema = Field(..., description="The frequency of the billing cycle.")
+    tenure_type: Literal['REGULAR', 'TRIAL'] = Field(..., description="The type of billing cycle tenure.")
+    sequence: int = Field(..., description="The sequence of the billing cycle.")
+    total_cycles: Optional[int] = Field(None, description="The total number of cycles in the billing plan.")
+    pricing_scheme: PricingSchemeSchema = Field(..., description="The pricing scheme for the billing cycle.")
+
+# Setup Fee Schema
+class SetupFeeSchema(BaseModel):
+    currency_code: Optional[Literal['USD']] = Field(None, description="The currency code for the setup fee.")
+    value: Optional[str] = Field(None, description="The value of the setup fee.")
+
+# Payment Preferences Schema
+class PaymentPreferencesSchema(BaseModel):
+    auto_bill_outstanding: Optional[bool] = Field(None, description="Indicates whether to automatically bill outstanding amounts.")
+    setup_fee: Optional[SetupFeeSchema] = Field(None, description="The setup fee for the subscription plan.")
+    setup_fee_failure_action: Optional[Literal['CONTINUE', 'CANCEL']] = Field(None, description="The action to take if the setup fee payment fails.")
+    payment_failure_threshold: Optional[int] = Field(None, description="The number of failed payments before the subscription is canceled.")
+
+# Taxes Schema
+class TaxesSchema(BaseModel):
+    percentage: Optional[str] = Field(None, description="The tax percentage.")
+    inclusive: Optional[bool] = Field(None, description="Indicates whether the tax is inclusive.")
+
+# Create Subscription Plan Parameters
+class CreateSubscriptionPlanParameters(BaseModel):
+    product_id: str = Field(..., description="The ID of the product for which to create the plan.")
+    name: str = Field(..., description="The subscription plan name.")
+    description: Optional[str] = Field(None, description="The subscription plan description.")
+    billing_cycles: List[BillingCycleSchema] = Field(..., description="The billing cycles of the plan.")
+    payment_preferences: PaymentPreferencesSchema = Field(..., description="The payment preferences for the subscription plan.")
+    taxes: Optional[TaxesSchema] = Field(None, description="The tax details.")
+
+# List Subscription Plans Parameters
+class ListSubscriptionPlansParameters(BaseModel):
+    product_id: Optional[str] = Field(None, description="The ID of the product for which to get subscription plans.")
+    page: Optional[int] = Field(None, description="The page number of the result set to fetch.")
+    page_size: Optional[int] = Field(None, description="The number of records to return per page (maximum 100).")
+    total_required: Optional[bool] = Field(None, description="Indicates whether the response should include the total count of plans.")
+
+# Show Subscription Plan Details Parameters
+class ShowSubscriptionPlanDetailsParameters(BaseModel):
+    plan_id: str = Field(..., description="The ID of the subscription plan to show.")
+
+# Name Schema
+class NameSchema(BaseModel):
+    given_name: Optional[str] = Field(None, description="The subscriber given name.")
+    surname: Optional[str] = Field(None, description="The subscriber last name.")
+
+# Address Schema
+class AddressSchema(BaseModel):
+    address_line_1: str = Field(..., description="The first line of the address.")
+    address_line_2: Optional[str] = Field(None, description="The second line of the address.")
+    admin_area_1: str = Field(..., description="The city or locality.")
+    admin_area_2: str = Field(..., description="The state or province.")
+    postal_code: str = Field(..., description="The postal code.")
+    country_code: Literal['US'] = Field(..., description="The country code.")
+
+# Shipping Address Schema
+class ShippingAddressSchema(BaseModel):
+    name: Optional[NameSchema] = Field(None, description="The subscriber shipping address name.")
+    address: Optional[AddressSchema] = Field(None, description="The subscriber shipping address.")
+
+# Payment Method Schema
+class PaymentMethodSchema(BaseModel):
+    payer_selected: Literal['PAYPAL', 'CREDIT_CARD'] = Field(..., description="The payment method selected by the payer.")
+    payee_preferred: Optional[Literal['IMMEDIATE_PAYMENT_REQUIRED', 'INSTANT_FUNDING_SOURCE']] = Field(None, description="The preferred payment method for the payee.")
+
+# Shipping Amount Schema
+class ShippingAmountSchema(BaseModel):
+    currency_code: Literal['USD'] = Field(..., description="The currency code for the shipping amount.")
+    value: str = Field(..., description="The value of the shipping amount.")
+
+# Subscriber Schema
+class SubscriberSchema(BaseModel):
+    name: Optional[NameSchema] = Field(None, description="The subscriber name.")
+    email_address: Optional[str] = Field(None, description="The subscriber email address.")
+    shipping_address: Optional[ShippingAddressSchema] = Field(None, description="The subscriber shipping address.")
+
+# Application Context Schema
+class ApplicationContextSchema(BaseModel):
+    brand_name: str = Field(..., description="The brand name.")
+    locale: Optional[str] = Field(None, description="The locale for the subscription.")
+    shipping_preference: Optional[Literal['SET_PROVIDED_ADDRESS', 'GET_FROM_FILE']] = Field(None, description="The shipping preference.")
+    user_action: Optional[Literal['SUBSCRIBE_NOW', 'CONTINUE']] = Field(None, description="The user action.")
+    return_url: str = Field(..., description="The return URL after the subscription is created.")
+    cancel_url: str = Field(..., description="The cancel URL if the user cancels the subscription.")
+    payment_method: Optional[PaymentMethodSchema] = Field(None, description="The payment method details.")
+
+# Create Subscription Parameters
+class CreateSubscriptionParameters(BaseModel):
+    plan_id: str = Field(..., description="The ID of the subscription plan to create.")
+    quantity: Optional[int] = Field(None, description="The quantity of the product in the subscription.")
+    shipping_amount: Optional[ShippingAmountSchema] = Field(None, description="The shipping amount for the subscription.")
+    subscriber: Optional[SubscriberSchema] = Field(None, description="The subscriber details.")
+    application_context: Optional[ApplicationContextSchema] = Field(None, description="The application context for the subscription.")
+
+# Show Subscription Details Parameters
+class ShowSubscriptionDetailsParameters(BaseModel):
+    subscription_id: str = Field(..., description="The ID of the subscription to show details.")
+
+class Reason(BaseModel):
+    reason: str = Field(..., description="Reason for Cancellation.")
+
+# Cancel Subscription Parameters
+class CancelSubscriptionParameters(BaseModel):
+    subscription_id: str = Field(..., description="The ID of the subscription to cancel.")
+    payload: Reason = Field(..., description="Reason for cancellation.")
+