Metadata-Version: 2.5
Name: appnigma-sdk
Version: 1.0.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
connects end customers, reads and writes their contacts, companies and deals
in one shape whichever CRM they use, runs your own functions, and calls any
platform's API. 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.

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 function's `output` and its
schemas, a platform's `headers` and `body`, a CRM record's `raw` and the names
in its `custom_fields`.

## 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 read and write")
```

`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 and write an end
customer's CRM in one shape, whichever CRM they use. Each has `list`, `get`,
`create` and `update`, and each takes `end_customer_id` and `platform`.
`end_customer_id` is your own id for your customer, 1 to 100 characters of
letters, digits, dot, dash or underscore.

```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.

### Writing: create and update

`create` makes a record and `update` changes one, from the fields you give in
the shapes they are read in. Both answer the record as `get` reads it.

```python
contact = client.crm.contacts.create(
    end_customer_id="lawfirm-123",
    platform="hubspot",
    record={
        "first_name": "Jane",
        "last_name": "Doe",
        "emails": [{"value": "jane@firm.com", "type": "work", "primary": True}],
    },
)["record"]

client.crm.contacts.update(
    end_customer_id="lawfirm-123", platform="hubspot", id=contact["id"], record={"last_name": "King", "owner_id": None}
)

client.crm.deals.create(
    end_customer_id="lawfirm-123",
    platform="pipedrive",
    record={"name": "Retainer", "amount": 1200, "currency": "USD"},
    match_key="inv_1042",
)
```

- **What you can write.** The fields in the table above, except `id`,
  `platform`, the times, `custom_fields`, `raw` and a deal's `closed_at`, which
  are the CRM's to set. A stage or a pipeline is written as its id.
- **`None` clears a field;** a field left out is left alone.
- **Matching.** A contact with an email, or a company with a domain, updates
  the record the CRM already has with it rather than making a second one. A
  deal has no such field, so pass `match_key`, a key of your own such as your
  invoice id: the same key updates the same deal.
- **Repeats.** A create that matches, and an update, are retried like reads,
  because a repeat changes the same record. A create with nothing to match on
  is made once, because a repeat could make a second record.
- **Refusals.** A field this CRM cannot be told is an `InputError` naming it,
  sent nowhere. A write the end customer's connection lacks the scope for is
  an `AuthError` with `MISSING_SCOPES`, and `details["missing"]` names the
  scopes: the end customer has to connect again. A value the CRM itself
  refuses is a `PlatformRefusedError` with its reason.

## Which platforms: platforms

`platforms.list` names each platform switched on for you, and how much of it
the shared shapes cover.

```python
for platform in client.platforms.list()["platforms"]:
    print(platform["label"], platform["support"])
```

`support` is `supported` when `crm` reads and writes it, with `coverage`
naming each object and its actions, or `experimental` when only `request`
reaches it so far.

## 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 a read; any other method is made
once, because only you know whether repeating it is harmless.

## Your own functions: catalog

Your microserver can also 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`. When the function's platform refuses
what it sent, it is a `PlatformRefusedError` carrying the platform's reason.

`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, reading and writing records,
`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, the platform is not switched on for you, or the end customer's connection lacks a scope a write needs (`MISSING_SCOPES`, with `details["missing"]`). 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. | |
| `PlatformRefusedError` | 422 with `PLATFORM_REFUSED`. The end customer's platform refused the call; `message` is its reason. Never retried: fix what you sent. | `platform_status`, the status the platform answered, or `None` |
| `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,
    PlatformRefusedError,
    RateLimitError,
    ReconnectError,
    ServerError,
)

try:
    client.crm.contacts.create(end_customer_id="lawfirm-123", platform="hubspot", record={"first_name": "Jane"})
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 PlatformRefusedError as error:
    print("the CRM refused it:", error.message)
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, 410
or 422 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`, `request` with a method other than `GET`,
and a `crm` create with nothing to match on 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; a create with nothing to match on could make a
second record. If one of them 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.crm.contacts.list(end_customer_id="lawfirm-123", platform="hubspot", 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 ten 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`.
