appnigma-sdk 0.1.0__tar.gz

appnigma_sdk-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules/
+dist/
+.turbo/
+*.tgz
+.env
+.DS_Store
+temp/
+*.gem
+ruby/.bundle/
+ruby/vendor/
+ruby/tmp/
+python/.venv/
+python/tmp/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

appnigma_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appnigma AI Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

appnigma_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,424 @@
+Metadata-Version: 2.5
+Name: appnigma-sdk
+Version: 0.1.0
+Summary: The package a customer's product installs to reach its Appnigma microserver
+Project-URL: Homepage, https://docs.appnigma.ai/sdk
+Project-URL: Source, https://github.com/Appnigma/ap-sdks/tree/main/python
+Project-URL: Issues, https://github.com/Appnigma/ap-sdks/issues
+Project-URL: Changelog, https://github.com/Appnigma/ap-sdks/releases
+Author-email: Appnigma <support@appnigma.ai>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.11
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: typing-extensions>=4.7.1
+Requires-Dist: urllib3<3.0.0,>=2.7.0
+Provides-Extra: dev
+Requires-Dist: build~=1.3; extra == 'dev'
+Requires-Dist: pytest~=9.0; extra == 'dev'
+Requires-Dist: ruff~=0.17.0; extra == 'dev'
+Requires-Dist: twine~=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# appnigma-sdk
+
+The package your product installs to reach its Appnigma microserver. It sends
+records to an end customer's HubSpot, reads them back, reads contacts,
+companies and deals in one shape whichever CRM they use, runs your own
+functions, calls any platform's API, and connects end customers. One package
+for every customer. Nothing about your account is inside it, and it holds no
+secret: the key is yours to supply.
+
+- Python 3.11 or newer. Tested on 3.11, 3.12, 3.13, 3.14 and 3.15.
+- The same calls, error codes and retry rules as the TypeScript package
+  `@appnigma/sdk`, with names in Python style.
+- Not tied to Django, Flask or any framework.
+
+## Install
+
+```sh
+pip install appnigma-sdk
+```
+
+The package is installed as `appnigma-sdk` and imported as `appnigma`.
+
+## The key
+
+Every call carries your SDK key. Appnigma gives you your key when your
+microserver is set up; ask Appnigma for a new one if you need to replace or
+cancel it. It starts with `apn_live_` and is shown once. Keep it on your
+server, in the `APPNIGMA_SDK_KEY` environment variable, never in a browser or
+a repo. The client reads it from there:
+
+```python
+from appnigma import Appnigma
+
+client = Appnigma()
+```
+
+If you keep the key somewhere else, pass it in; a passed key wins:
+
+```python
+client = Appnigma(key=vault.read("appnigma-sdk-key"))
+```
+
+A client started with no key at all, or with a key that does not start with
+`apn_live_`, raises `AuthError` at once, before any call.
+
+## The first call: post a record
+
+`post` creates a record or updates the one that already matches. For a
+contact, the match is on `email` unless you name another property with
+`unique_by`. For a company or a deal, `unique_by` is required: name a property
+the platform treats as unique, and include it in `record` with a non-empty
+text value. Because it is an update when the record exists, a repeated call is
+safe.
+
+```python
+result = client.post(
+    end_customer_id="lawfirm-123",
+    platform="hubspot",
+    object="contact",
+    record={"email": "jane@firm.com", "firstname": "Jane", "lastname": "Doe"},
+)
+print("created" if result["created"] else "updated", result["id"])
+```
+
+`end_customer_id` is your own id for your customer, 1 to 100 characters of
+letters, digits, dot, dash or underscore. `platform` is required, and `post`
+and `pull` work on `hubspot` only for now. `object` is `contact`, `company` or
+`deal`. `record` uses the platform's own property names.
+
+Every argument is passed by name. Every answer is a plain `dict` with keys in
+Python style (`expires_at`, `input_schema`), except content that is not ours,
+which comes back exactly as it was sent: a record's `properties`, a function's
+`output` and its schemas, a platform's `headers` and `body`, a CRM record's
+`raw` and the names in its `custom_fields`.
+
+## Reading back: pull
+
+`pull` returns one page of records and a marker for the next. `next` is `None`
+on the last page.
+
+```python
+after = None
+while True:
+    page = client.pull(end_customer_id="lawfirm-123", platform="hubspot", object="contact", limit=100, after=after)
+    for contact in page["records"]:
+        print(contact["id"], contact["properties"]["email"])
+    after = page["next"]
+    if after is None:
+        break
+```
+
+`limit` is 1 to 100 and defaults to 100.
+
+## Connecting an end customer
+
+Before calls can work for an end customer, they connect their account on that
+platform once. Any platform switched on for your company can be connected, and
+the end customer approves your own app there. Your product asks for a link,
+shows it to the end customer, and they approve on the platform.
+
+1. Ask for a link. It works once and expires after 15 minutes. Opening it does
+   not use it up: it is used when the end customer presses Connect, so a mail
+   scanner or a link preview opening it first does no harm.
+2. Send the end customer to the link's `url`. They log in to the platform and
+   approve.
+3. When they are done, they land on your `return_url` with `status=connected`,
+   or with `status=failed` and a `reason`. `return_url` must be HTTPS and at
+   most 2048 bytes when written as a JSON string, about 2046 plain characters.
+4. Confirm with `connections.get`. The connection is written before the end
+   customer lands, so the answer is already there.
+
+```python
+link = client.connections.create_link(
+    end_customer_id="lawfirm-123",
+    platform="hubspot",
+    return_url="https://app.example.com/integrations/hubspot/done",
+)
+print(f"send the end customer to {link['url']} before {link['expires_at']}")
+
+connection = client.connections.get(end_customer_id="lawfirm-123", platform="hubspot")
+if connection["status"] == "connected":
+    print("ready to post and pull")
+```
+
+`status` is `connected`, `needs_reconnect` or `disconnected`. An end customer
+who is already connected can open a new link to connect again, for example
+after changing HubSpot accounts. An end customer the API has never seen is a
+`NotFoundError`, not a status.
+
+The id travels in the URL for this call, so an id that is only `.` or `..` is
+refused before the call with `InputError`: a URL drops those, and the request
+would reach the wrong route. Do not use them as end customer ids.
+
+## CRM data in one shape: crm
+
+`crm.contacts`, `crm.companies` and `crm.deals` read an end customer's CRM in
+one shape, whichever CRM they use. Each has `list` and `get`, and each takes
+`end_customer_id` and `platform`.
+
+```python
+page = client.crm.contacts.list(end_customer_id="lawfirm-123", platform="attio", limit=50)
+for contact in page["records"]:
+    email = contact["emails"][0]["value"] if contact["emails"] else None
+    print(contact["full_name"], email)
+
+# The next page, while there is one.
+if page["next"]:
+    client.crm.contacts.list(end_customer_id="lawfirm-123", platform="attio", cursor=page["next"])
+
+deal = client.crm.deals.get(end_customer_id="lawfirm-123", platform="hubspot", id="1234")["record"]
+print(deal["name"], deal["amount"], deal["currency"], deal["status"])
+```
+
+Every field is always there: a value the CRM does not have is `None`, never
+left out.
+
+| Object | Fields |
+| --- | --- |
+| Every record | `id`, `platform`, `created_at`, `updated_at`, `custom_fields`, and `raw`, the record exactly as the CRM sent it |
+| Contact | `first_name`, `last_name`, `full_name`, `emails`, `phones` (the primary one first), `company_id`, `owner_id` |
+| Company | `name`, `domain`, `owner_id` |
+| Deal | `name`, `amount`, `currency`, `status` (`open`, `won` or `lost`), `stage`, `pipeline`, `probability`, `close_date`, `closed_at`, `company_id`, `owner_id` |
+
+`custom_fields` is keyed by the CRM's own field names, and `raw` is exactly
+what the CRM sent. A platform with no unified data yet for that object is a
+`NotAvailableError` with `DATA_TYPE_NOT_AVAILABLE`; reach it with `request`
+instead. An id that does not exist is a `NotFoundError` with
+`RECORD_NOT_FOUND`. Reads are retried like `pull`.
+
+## Anything else on the platform: request
+
+`request` calls the end customer's platform's own API, for anything the shared
+shapes do not cover. It works on every platform switched on for you, including
+ones with no unified data yet.
+
+```python
+answer = client.request(
+    end_customer_id="lawfirm-123",
+    platform="hubspot",
+    method="GET",
+    path="/crm/v3/objects/notes?limit=10",
+)
+if answer["status"] == 200:
+    print(answer["body"])
+```
+
+`path` is a path on the platform's own API, with its query: never a full
+address, and it cannot step out of that API, so `..` and `//host` are refused.
+`body` is sent as JSON; leave it out on a `GET`.
+
+The answer is the platform's own: its `status`, its `headers` (content type,
+paging and rate limits) and its `body`, parsed from JSON when the platform
+answered JSON and as text otherwise. A refusal from the platform comes back
+the same way, with its status, rather than as an error: check
+`answer["status"]`. A `GET` is retried like `pull`; any other method is made
+once, because only you know whether repeating it is harmless.
+
+## Your own functions: catalog
+
+Beyond `post` and `pull`, your microserver can hold functions written for you.
+`catalog` lists them, with the platform each one is for and the JSON Schema of
+its input and output. Leave `platform` out for every platform,
+or name one to narrow the list.
+
+```python
+for function in client.catalog(platform="hubspot")["functions"]:
+    print(function["platform"], function["name"], function["description"])
+```
+
+A function's `owner` is `{"type": "customer"}` when every end customer can use
+it, or `{"type": "end_customer", "end_customer_id": "..."}` when it was
+written for one of them. `input_schema` and `output_schema` are JSON Schema,
+as written. Each function has one live version: a change to it replaces it
+when the change goes live. Until a function has gone live for you, the list is
+empty, not an error.
+
+## Your own functions: run
+
+`run` calls one of them, by platform and name, for one end customer. The input
+is checked against the function's shape before anything runs, so a wrong or
+missing field is an `InputError` listing every problem. Formats and patterns,
+such as an email or a fixed layout for a code, are checked by the function
+itself, so those refusals arrive from it with the same code. The answer is
+`{"output": ..., "ran_as": ...}`: the output in the shape the function
+declared, with its keys as the function wrote them, and whose function ran.
+`ran_as["owner"]` is `"end_customer"` when the end customer has a function of
+their own by that name and it ran, `"customer"` when yours did;
+`ran_as["version"]` is the version that ran.
+
+```python
+result = client.run(
+    end_customer_id="lawfirm-123",
+    platform="hubspot",
+    function_name="invoice-to-deal",
+    input={"invoiceId": "inv_1042", "amount": 1250},
+)
+print("deal", result["output"]["dealId"], "ran as", result["ran_as"]["owner"], result["ran_as"]["version"])
+```
+
+`platform` and `function_name` are both required: the same name can exist on
+two platforms and mean two different things. What runs is always the
+function's live version. A name that exists only on another platform is a
+`NotFoundError` whose `details["platforms"]` says which. A function that was
+live and was removed from your logic is retired: calling it is a
+`RetiredError` with `FUNCTION_RETIRED`, whose `details` name the function and
+when it was retired. A platform that is not switched on for you is an
+`AuthError` with `PLATFORM_NOT_ENABLED`.
+
+`run` is made once and never retried: it is your own function, and only you
+know whether running it twice is harmless. If it fails with a network or
+server error, decide in your code whether to call again.
+
+## Your own guide
+
+One page, written for your company: install, the key, connecting an end
+customer to each platform switched on for you, `post`, `pull` and `run`, every
+one of your functions with its fields and an example call, and every error
+with what to do about it. `guide` answers it as markdown, built from what is
+live right now.
+
+```python
+from pathlib import Path
+
+Path("appnigma-guide.md").write_text(client.guide()["guide"])
+```
+
+## Telling failures apart
+
+Every failure is an exception you can catch by class. All of them inherit from
+`AppnigmaError`, so one `except AppnigmaError` catches anything from
+Appnigma. Every error carries `code`, `message`, `status` and `request_id`;
+`str(error)` is the message. Quote the request id when you write to
+support@appnigma.ai, and never include your key or a token.
+
+| Class | When | Extra field |
+| --- | --- | --- |
+| `InputError` | 400. A field is wrong or missing. Also raised locally for a bad setting or a bad end customer id, before any call. | `problems`, a list of `{"field": ..., "problem": ...}` |
+| `AuthError` | 401 or 403. The key is missing, unknown or cancelled, the microserver is not enabled, or the platform is not switched on for you. Also raised at start with no key. | |
+| `NotFoundError` | 404. No connection for that end customer on that platform, no such function, or no such record (`RECORD_NOT_FOUND`). When the function exists on another platform, `details["platforms"]` names it. | |
+| `ReconnectError` | 409 with `CONNECTION_NEEDS_RECONNECT`. The end customer has to approve again. | |
+| `NotAvailableError` | Any other 409. The platform has no unified data for that yet (`DATA_TYPE_NOT_AVAILABLE`); use `request`. | |
+| `RetiredError` | 410 with `FUNCTION_RETIRED`. The function was live and was removed from your logic; it will not answer again. | |
+| `RateLimitError` | 429, after the retries. Too many calls, or the platform asked us to slow down. | `retry_after_seconds`, or `None` when the server named no wait |
+| `ServerError` | Any 5xx, after the retries. Also any successful answer whose body is not JSON. | |
+| `NetworkError` | The API could not be reached, or an attempt ran out of time, after the retries. `status` and `request_id` are `None`. | `__cause__`, the underlying exception |
+
+```python
+from appnigma import (
+    AuthError,
+    InputError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ReconnectError,
+    ServerError,
+)
+
+try:
+    client.post(end_customer_id="lawfirm-123", platform="hubspot", object="contact", record={})
+except InputError as error:
+    for problem in error.problems:
+        print(problem["field"], problem["problem"])
+except AuthError as error:
+    print("check the key:", error.code)
+except NotFoundError:
+    print("this end customer is not connected yet")
+except ReconnectError:
+    print("ask the end customer to connect again")
+except RateLimitError as error:
+    print(f"wait {error.retry_after_seconds} seconds")
+except ServerError as error:
+    print("our side failed, quote this id to support:", error.request_id)
+except NetworkError as error:
+    print("could not reach the API:", error.__cause__)
+```
+
+Or catch the base class:
+
+```python
+from appnigma import AppnigmaError
+
+try:
+    client.connections.get(end_customer_id="nobody-here", platform="hubspot")
+except AppnigmaError as error:
+    print(type(error).__name__, error.code, error.status, error.request_id)
+```
+
+`code` is one of the strings in `ERROR_CODES`, or whatever a newer server
+sent. A code this version of the package does not know is kept as is, never
+replaced.
+
+## Retries and time limits
+
+A call is tried again only when trying again is safe: the API could not be
+reached, it answered 5xx, or it answered 429. A 400, 401, 403, 404, 409 or 410
+is never retried, because the same call would be refused the same way. By default
+a call is made up to three times.
+
+`connections.create_link`, `run`, and `request` with a method other than `GET`
+are the exceptions: each is made once, never retried. Every call to
+`create_link` makes a new link, and a repeat after a lost answer would leave a
+working link nobody saw; `run` is your own function, and whether a repeat is
+harmless is yours to know. If either fails, decide in your code whether to
+call again.
+
+The wait between tries is what the `Retry-After` header says when the server
+sent one, otherwise half a second and then a second, with a little random
+spread so many clients do not retry in the same instant. A `Retry-After`
+longer than `max_retry_wait_ms` is not waited for: the call fails at once with
+a `RateLimitError` that carries the wait, so your code decides what to do with
+half a minute rather than sitting through it.
+
+Every attempt has a time limit, 30 seconds by default. An attempt that runs out
+of time counts as a network failure and is retried like one. Each call can set
+its own limit:
+
+```python
+page = client.pull(end_customer_id="lawfirm-123", platform="hubspot", object="contact", limit=1, timeout_ms=10_000)
+print("one record:", len(page["records"]))
+```
+
+Times are in milliseconds, as in the TypeScript and Ruby packages, so the
+numbers are the same in all three.
+
+## Settings
+
+All passed to `Appnigma()`, and all optional. `key` can be passed first
+without its name; the rest are passed by name.
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `key` | the `APPNIGMA_SDK_KEY` environment variable | Your SDK key. |
+| `timeout_ms` | `30_000` | How long one attempt may take. A whole number of milliseconds, at most 2147483647. |
+| `max_retries` | `2` | How many times a call is tried again. `0` means one attempt. |
+| `max_retry_wait_ms` | `30_000` | The longest `Retry-After` the client will sit through, in milliseconds, at most 2147483647. |
+
+Per call, by name: `timeout_ms`.
+
+## What is exported
+
+From `appnigma`: `Appnigma`, `AppnigmaError` and its nine subclasses, the
+constants `ERROR_CODES`, `OBJECTS`, `CONNECTION_STATUSES` and
+`PLATFORM_REQUEST_METHODS`, `__version__`, and `API_DESCRIPTION_VERSION`, the
+version of the published description of the API that this version of the
+package was generated from. Names that start with an underscore are not part
+of the package's interface and can change in any release.
+
+## License
+
+MIT. See `LICENSE`.