Metadata-Version: 2.4
Name: magicfeedback
Version: 1.0.26
Summary: SDK for the Deepdots API (formerly MagicFeedback)
Home-page: https://github.com/MagicFeedback/magicfeedback_python_sdk
Author: Francisco Arias
Author-email: Francisco Arias <farias@magicfeedback.io>
Project-URL: Homepage, https://github.com/MagicFeedback/magicfeedback_python_sdk
Project-URL: Issues, https://github.com/MagicFeedback/magicfeedback_python_sdk/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: requests>=2.0.0
Requires-Dist: google-cloud-pubsub>=2.0.0
Requires-Dist: google-cloud-datastore>=2.16.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Deepdots Python SDK

Python SDK for the Deepdots API (the company was formerly called MagicFeedback).

## Installation

```bash
pip install deepdots
```

The original distribution is still published and still works:

```bash
pip install magicfeedback
```

## Naming

MagicFeedback was renamed **Deepdots**. Both sets of names work and refer to the
*same* objects, so **no existing code needs to change**:

| | Current name | Original name |
|---|---|---|
| PyPI distribution | `deepdots` | `magicfeedback` |
| Import package | `deepdots_sdk` | `magicfeedback_sdk` |
| Client class | `Deepdots` | `MagicFeedback` |

Distribution names are written lowercase throughout — that is the packaging
convention, and PyPI treats names case-insensitively anyway, so
`pip install MagicFeedback` keeps working for anyone who has it written that way.

`deepdots_sdk` re-exports `magicfeedback_sdk` module by module, and `Deepdots`
is the same class object as `MagicFeedback` — `MagicFeedback is Deepdots` is
`True`, so `isinstance()` checks and subclasses behave identically. Submodule
imports work under either name (`from deepdots_sdk.api.feedback import
FeedbackAPI`). New code should prefer the Deepdots names.

## Usage

```python
from deepdots_sdk import Deepdots

# With an API user's email and password.
client = Deepdots("email", "password", auth_source="identity",
                  base_url="https://api.deepdots.com")
```

The original names remain fully supported:

```python
from magicfeedback_sdk import MagicFeedback

client = MagicFeedback("email", "password")
```

## Authentication

The client signs in through the API (`POST /auth/token`), which asks Identity
Platform for the token. The SDK no longer calls Identity Platform itself, so it
needs no Identity Platform key: the `ip_key` argument is ignored (with a
`DeprecationWarning`). The token lasts one hour; the client keeps the refresh
token the API returns.

The token is resolved from one of two sources, selected with `auth_source`:

- `"datastore"` **(default)** — read the token cached in Google Cloud Datastore
  by the `update-token` job (kind `token-storage`, email
  `robot@magicfeedback.io`, database `shared`). This avoids a sign-in on every
  use. If the cached token is missing, stale (older than `token_max_age_min`,
  default 50 min) or Datastore is unreachable, the client falls back to
  signing in with `user`/`password`.
- `"identity"` — always sign in with `user`/`password`, with no Datastore
  lookup. Use it outside Deepdots' own Google Cloud projects, where the
  Datastore cache can't be read.

```python
# Datastore-cached token (default), signing in as the fallback.
# email/password are only needed for the fallback.
client = MagicFeedback("email", "password")

# Tune the Datastore lookup (all optional; shown with their defaults):
client = MagicFeedback(
    "email", "password",
    auth_source="datastore",
    gcp_project_id=None,             # None => inferred from Application Default Credentials
    datastore_database_id="shared",
    token_kind="token-storage",
    token_email="robot@magicfeedback.io",
    token_max_age_min=50,
    datastore_timeout_s=5.0,         # cap the lookup so the fallback stays fast
)

# Always sign in with email and password:
client = MagicFeedback("email", "password", auth_source="identity")
```

A wrong email or password raises `requests.HTTPError` with a **401** (the same
for both, so the API does not tell which accounts exist); a disabled user is a
**403**, and too many failed attempts on the account a **429**.

The Datastore lookup is bounded by `datastore_timeout_s` (default 5s): if the
cache is unreachable or the credentials are stale, the client falls back to
signing in within that budget instead of blocking on the Datastore client's
default ~60s retry deadline.

The Datastore path needs the `google-cloud-datastore` package (installed as a
dependency) and Google Application Default Credentials with read access to the
token entity (`gcloud auth application-default login` or
`GOOGLE_APPLICATION_CREDENTIALS`).

Helper methods:

- `client.refresh_token()` — renew the token and update the auth header in
  place across all sub-API clients. With `auth_source="identity"` it uses the
  refresh token (`POST /auth/token/refresh`), and signs in again if that was
  rejected; with `"datastore"` it re-reads the cache (signing in as the
  fallback). Useful for long-lived clients whose token has expired:
  `client.crm` calls it by itself on a 401.
- `client.auth.get_token_from_datastore(allow_stale=False)` — read the cached
  token directly; returns `None` when missing, stale or unreachable.

## API Reference

### `client.feedbacks`
- `create(feedback)` — creates a feedback via `POST /feedbacks`. The dict becomes the JSON body with your keys unchanged, so every field is top-level (the SDK only wraps a scalar `value` into a list, see below, and adds a missing `companyId`/`productId`, see next). The SDK requires `name`, `type`, `identity` and `integrationId` (it raises `ValueError` before sending if one is missing). `companyId` and `productId` are optional (since 1.0.25): when one is missing or empty (`None` or `""`), `create()` copies it from the integration, which it reads once per `integrationId` (`GET /integrations/{id}`) and keeps for the life of the client (an integration without a company or product is read again on each call) — after moving an integration to another product, create a new client or pass `productId`. Non-empty values you pass are kept, and the copied values go into the request only, not into your dict. If you already send `productId`, keep sending the same value: `external_id` deduplication matches company, product and integration, so a different product makes re-sent feedbacks new ones. The API can fill them from the integration too, but when your user can't read it, it files the feedback under your user's own company with no product; reading the integration in the SDK makes that case an error instead. If the integration has no company, or has no product and you don't pass `productId`, or belongs to another company than the `companyId` you pass, `create()` raises `ValueError`; if the API refuses the read (**406** for an integration that doesn't exist, was deleted or deprecated, or your user can't see; **405** if your role can't read integrations), it raises `requests.HTTPError`. Nothing is created in either case, and passing both fields skips the lookup. Use the `identity` of the integration the feedback belongs to: survey identities such as `MAGICFORM`, `MAGICSURVEY` and `CSV` analyse `answers`, while most others, such as `GENERAL` and `CUSTOM`, analyse only `text`, and some accepted values are not analysed at all. Optional fields include `text`, `answers`, `metadata`, `metrics`, `crmContactId` and the source-system fields `external_id`, `externalGeneratedAt`, `externalUpdatedAt` and `externalUrl` — see [Feedback source-system fields](#feedback-source-system-fields). Keys are case-sensitive. A misspelled required key (e.g. `integration_id` instead of `integrationId`) makes the SDK raise `ValueError: Missing required field: integrationId`; any other key the API does not accept is rejected with **422** and nothing is created — a misspelling such as `company_id` or `externalId`, or a server-set field such as `id`, `status` or `createdAt`. When `external_id` matches an existing, non-deleted feedback of the same company, product and integration, the API returns that feedback **unchanged** (HTTP 200, nothing written) instead of creating a duplicate.
- `get(filter=None)` — lists feedback items. To find the feedback an SDK session became, filter on the `sessionId` that `POST /sdk/feedback` returned: `get(filter={"where": {"sdkSessionId": session_id}, "order": ["createdAt DESC"]})`. Set only on feedbacks created after the field shipped. Since 2026-10-07 a session that closes again updates the feedback it already has, so a session normally maps to one feedback. A session can still have two (one that closed twice between 2026-09-30 and 2026-10-07, or whose first feedback was deleted), so keep the `order` and take the first result.
- `get_id(feedback_id, filter=None)` — retrieves a specific feedback item.
- `update(feedback_id, feedback)` — `PATCH /feedbacks/{id}` with only the fields you pass; returns `{}` (the API answers 204). `external_id`, `type`, `identity`, `integrationId`, `productId`, `profile` and `data` cannot be changed (422), so never PATCH back a whole object read from `get_id()`. The change is saved immediately, but charts and reports pick up changes to the date, `text`, `answers`, `metrics` or `metadata` only when the feedback is re-analysed: include `"status": "REGISTERED"` in the same call to queue a full re-analysis — read what that does at the end of [Feedback source-system fields](#feedback-source-system-fields) first. `update()` needs an API user whose role may update feedback (otherwise **405**).
- `update_metadata_batch(items, mode=None)` — merges metadata into **many feedbacks in one request** and triggers re-analysis for each, so the change propagates through the analysis pipeline to BigQuery (`insight.metadata`) and the metadata table. `items` is a list of `{"feedbackId": ..., "metadata": [{"name": ..., "values": [...]}]}`; each metadata entry may use the SDK-native `{"key": ..., "value": ...}` shape instead, and a bare scalar value is wrapped into a list. Semantics are **additive** (upsert by key): the keys you send are added, or their values overwritten if the key already exists — every other existing key is kept, and **nothing is ever deleted** (an item with no metadata is a no-op). Pass `mode="append"` to add the values you send to the ones a key already holds instead of overwriting them (values it holds already are skipped, so a retry adds nothing twice) — use it for event-log keys such as `deepdots_message`, which the default would wipe. Feedbacks not listed are untouched. The feedback ids are checked **all or nothing**: if any does not exist, is deprecated or belongs to a company you cannot see, the API answers **404** naming them and nothing is written (the SDK raises `requests.HTTPError`); only a failure writing or re-queuing one feedback is listed in `failed` while the rest still land. Each updated feedback re-runs the full analysis pipeline. Returns e.g. `{"feedbacks": N, "triggered": M, "failed": [...]}`.
- `delete(feedback_id)` — soft-deletes the feedback: its status becomes `DEPRECATED`, it disappears from `get_id`, dashboards and reports, and from `get` unless your filter's `where` sets `status`; the SDK has no way to restore it. Returns `{}`. A later `create()` with the same `external_id` makes a new feedback.
- `upload_attachment(feedback_id, file_path, filename=None, extra_data=None, max_attachments=3, check_duplicate_content=True)` — uploads a file and attaches it to a feedback. Before uploading it fetches the feedback's existing attachments and enforces two guards (nothing is uploaded if either trips): a **maximum of `max_attachments` files** (default 3) per feedback, and **no duplicate content** — the new file's bytes are SHA-256 hashed and compared against each existing attachment by *content*, not filename, so re-attaching the same file under a different name raises `ValueError`. The duplicate check downloads each existing attachment to hash it (best-effort — attachments it cannot download, e.g. a private bucket returning 403, are skipped); pass `check_duplicate_content=False` to disable it. The cap fails **closed**: if the feedback's current attachments can't be fetched, the upload is refused rather than risk exceeding the limit.

`create`, `update`, `get` and `get_id` all normalize the `answers`,
`metadata`, `metrics` and `profile` fields: each entry is `{"key": ...,
"value": ...}`, and the raw API is inconsistent about `value`'s shape — the
same feedback can have one entry with a bare scalar (`"value": "voice"`) next
to another with a list (`"value": ["sln"]`). The SDK wraps every bare scalar
as `[value]`, both on what it sends (create/update) and on what it returns
(get/get_id), so callers only ever see/send the list form. `questions` is a
different shape (`title`/`ref`/`position`/...) and is left untouched; `data`
is not currently normalized. (`profile` can only be sent with `create()`:
`update()` rejects it with 422.)

#### Feedback source-system fields

When feedback comes from another system (a helpdesk, a review site, a CSV
export...), send these optional fields with `create()`. They go at the top
level, next to `integrationId`, not inside `answers` or
`metadata`:

| Field | Meaning |
|---|---|
| `external_id` | ID of the record in the source system, as a string (`"48213"`, not `48213`). Makes `create()` safe to retry: re-sending an id that already exists for the same company, product and integration returns the existing feedback unchanged and never updates it. Send retries for the same id one after another, not in parallel: two simultaneous requests can both create a feedback. Without it nothing is deduplicated, and a retry creates a second copy. |
| `externalGeneratedAt` | When the feedback happened in the source system. **This is the date dashboards, reports and date filters use.** If it is omitted, the API stores the time it received the request, so a historical import lands entirely on the import day. |
| `externalUpdatedAt` | When the record last changed in the source system (defaults to the request time). |
| `externalUrl` | Link to the original record, shown as the feedback's *Original source* link. |

The casing is mixed: `external_id` is the only snake_case field, and every
other field is camelCase (`companyId`, not `company_id`).

Send both dates as **UTC ISO 8601 strings ending in `Z`**, e.g.
`"2026-10-06T11:00:00.000Z"` (JavaScript's `toISOString()` format). The API
stores any string without checking it, but analytics can only read
`YYYY-MM-DDTHH:MM:SS[.ffffff]Z`, or `YYYY-MM-DDTHH:MM:SS` with no fraction and
no zone (charts read it as UTC, but the dashboard's feedback list shows it
unconverted, as if it were the viewer's local time, so add the `Z`). Any other
value is still stored, but analytics can't use it, and in `externalGeneratedAt`
it makes the feedback drop out of date-filtered charts and reports. That
includes an offset such as `+02:00` (Python's default `isoformat()` of an aware
datetime), fractional seconds without the `Z` (`isoformat()` of a naive
datetime that has microseconds, such as `datetime.utcnow()`), more than six
fractional digits, a date without a time, and a space instead of `T`. The API stores the value as text, so filters and
sorting compare it as a string. A `datetime` object raises `TypeError` in the
SDK, and `None` or a number gets a 422.

```python
from datetime import datetime, timezone
from zoneinfo import ZoneInfo  # Python 3.9+; on Windows also: pip install tzdata

def to_api_datetime(dt):
    """Timezone-aware datetime -> '2026-10-06T11:00:00.000Z'."""
    if dt.utcoffset() is None:
        raise ValueError("Naive datetime: attach the source time zone first, e.g. dt.replace(tzinfo=ZoneInfo('Europe/Copenhagen'))")
    return dt.astimezone(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
```

The helper refuses naive datetimes because `astimezone()` would treat them as
machine-local time: attach the source zone first
(`dt.replace(tzinfo=ZoneInfo("Europe/Copenhagen"))`).

Re-sending a feedback does not fix its date (see `external_id`). Instead,
PATCH the date and re-run the analysis in the same call:

```python
client.feedbacks.update(feedback_id, {
    "externalGeneratedAt": "2026-10-06T11:00:00.000Z",
    "status": "REGISTERED",
})
```

Like every `update()` that sends `"status": "REGISTERED"`, that is a full re-analysis:
- The summary, issues and topics are regenerated, and issue triage starts over.
- Automations on feedback completion fire again.
- Once the new analysis finishes `DONE`, charts and reports can take up to an
  hour to settle. Check with `get_id()` that `status` is back to `DONE`: if the
  run ends `PARTIAL` or `ERROR`, charts keep showing the old date until a later
  analysis finishes `DONE`: send the same update again.

Send `"status": "REGISTERED"` only once the feedback has finished processing;
while it is still `REGISTERED` or `PROCESSING` it starts a second analysis.
If some feedbacks stay `REGISTERED` or `PROCESSING` long after the rest have
finished, they are probably not being analysed at all (for example because an
answer value is a number, or their `identity` is not analysed); ask your
Deepdots contact instead of re-sending them.
Patching the date without `"status": "REGISTERED"` updates the stored feedback
only, and charts and reports keep the old date until it is next re-analysed.
Any `update()` of a feedback whose status is `DONE`, even without `status`,
fires the feedback-completion automations again. The API user needs a role
with feedback-update permission (otherwise 405). Don't send an empty
`externalGeneratedAt` to `update()`: unlike `create()`, `update()` stores it as
it is, and the feedback then drops out of date-filtered charts and reports. If
you need to re-analyse many feedbacks, talk to your Deepdots contact before you
start.

### `client.contacts`
- `create(contact)`, `get(filter=None)`, `update(contact_id, contact)`, `delete(contact_id)`. When `create()` sends an `externalId` the company already has, whatever that contact's status, no contact is added: the API returns that contact updated with the fields you sent (`email` included, `customFields` merged) and brings it back to ACTIVE if it was deleted; an unsubscribed contact stays unsubscribed, and if your role can't update contacts it comes back unchanged. Without an `externalId`, `create()` always adds a contact, even for an email the company already has. This is a check before inserting, not a unique constraint: a company can still have several contacts with the same `externalId`.
- `upsert(contact)` — **create-or-update** a single contact via `POST /crm/contacts/upsert`. Prefer this over `create()` when the record may already exist. It updates the company's ACTIVE contact with the same email; if there is none, the contact holding the `externalId` you send, which then takes your email and comes back to ACTIVE if it was deleted; otherwise it creates one. Only ACTIVE contacts are matched by email: an unsubscribed or deleted contact is found only through the `externalId` you send, and without it `upsert()` creates a new ACTIVE contact with the same email. On the update branch scalars are overwritten and `customFields` is **merged** (same additive semantics as `update_fields`); the key the contact was matched by (its email, or its `externalId`) is never rewritten. `name`, `email`, `companyId` are required. Returns the contact after the upsert.

  ```python
  client.contacts.upsert({
      "name": "Ada", "email": "ada@example.com", "companyId": "ACME",
      "customFields": {"loyalty_tier": "gold"},
  })
  ```
- `upsert_batch(items, chunk_size=500)` — upsert **many** contacts via `POST /crm/contacts/upsert/batch`, automatically **chunking** `items` to the server cap (500) so you can pass a list of any length. Sending a batch is the pool-friendly way to do bulk (one sequential request per chunk instead of N parallel calls racing the DB connection pool). Best-effort per item: an item that fails on its own (bad email, inaccessible company, ...) is collected in `failed` and the rest still land. Returns aggregated `{"contacts", "created", "updated", "failed"}`; each `failed` entry's `index` points into the **original** `items` list.

  ```python
  result = client.contacts.upsert_batch([
      {"name": "Ada",  "email": "ada@example.com",  "companyId": "ACME", "customFields": {"tier": "gold"}},
      {"name": "Alan", "email": "alan@example.com", "companyId": "ACME"},
      # ... pass thousands; the SDK splits them into 500-item requests
  ])
  print(result["created"], result["updated"], result["failed"])
  ```
- `update_fields(contact_id, custom_fields=None, **native_fields)` — **additively** merge custom fields into a contact via `PATCH /crm/contacts/{id}/fields`. The refs you send are upserted, **every other custom field is kept**, and a value of `None` removes its ref. Prefer this over `update()` for custom fields: `update()` writes the `customFields` object whole, so setting one field there deletes all the others. `custom_fields` values may be `str`/`int`/`float`/`bool`. You may also pass native columns as keywords — `name`, `lastname`, `phone`, `address`, `city`, `state`, `postalCode` — anything else (`email`, `externalId`, `status`, `country`, `type`) is rejected with a 400; use `update()` for those. Returns `{"id": ..., "customFields": {...}}`, the full field set after the merge.

  ```python
  # Add / overwrite custom fields, keeping any others the contact already has
  client.contacts.update_fields(contact_id, {"loyalty_tier": "gold", "vip": True})

  # Remove a custom field
  client.contacts.update_fields(contact_id, {"loyalty_tier": None})

  # Custom fields + a native column in one call
  client.contacts.update_fields(contact_id, {"nps_segment": "promoter"}, city="Copenhagen")
  ```

### `client.crm`
CRM objects are the records a company keeps next to its contacts (tickets,
matches, memberships, ...). Each is stored as `(companyId, type, externalId)`
plus a free-form `data` object, and survey answers can be linked to them
through the survey link's URL parameters.

`upsert_objects` sends 500 records per request (pass a list of any length, or
one record as a dict) and returns totals over all requests, with each `failed`
entry's `index` pointing into the list you passed. Failures are per record: a
record the API cannot store is listed in `failed` and the others still land. A
request must stay under the API's 1 MB body limit: at the default 500 records
per request that is about 2 KB of JSON per record on average. For larger
records pass a smaller `chunk_size`.

Every request, reads included, is resent up to 3 times (after 2s, 4s, 8s) when
it fails temporarily (502/503/504, a connection error, or no answer within 300
s), and if the token has expired the client logs in again once and resends. If
a request still fails after that, the call raises a
`requests.RequestException` (`HTTPError` for an error answer, `ConnectionError`
or `Timeout` for the network); the requests before it have already been
applied.

Resending records never creates duplicates: they are matched by their
`externalId`. Items with `sourceUpdatedAt` keep the newest version, while items
without it store the last one sent. So after a failure, resend the same list
right away, but never resend an older export after newer changes have been
sent.

- `upsert_objects(object_type, items, company_id=None, chunk_size=500)` —
  create-or-update objects of one type via `POST
  /crm/objects/{type}/upsert/batch`, matched by `externalId` (required). Other
  item fields: `status`, `contactKey`, `parentType`, `parentKey`, `startsAt`,
  `endsAt`, `sourceUpdatedAt`, `data`. A field left out keeps what is stored,
  and `data` is merged key by key. Returns `{"count", "created", "updated",
  "failed"}`.
- `get_objects(object_type, company_id=None, external_id=None, status=None,
  parent_type=None, parent_key=None, contact_key=None, limit=None, after=None)`
  — list objects of one type, ordered by `externalId`, via `GET
  /crm/objects/{type}`. Filters match exactly. Pages hold `limit` objects
  (default 100, max 1000); for the next page pass the last `externalId` as
  `after`.

`company_id` is required for admin accounts (the API answers 400 without it).
Other users read and write their own company by default; they can also name
another company they belong to, and any other company is refused with 403.

```python
from deepdots_sdk import Deepdots

client = Deepdots("api-user@example.com", "password",
                  auth_source="identity", base_url="https://api.deepdots.com")

result = client.crm.upsert_objects("match", [
    {"externalId": "1001", "startsAt": "2026-11-15T16:00:00Z",
     "data": {"name": "Northside - Riverside"}},
])
print(result["created"], result["updated"], result["failed"])

tickets = client.crm.get_objects("ticket", contact_key="C-1001")
```

### `client.campaigns`
- `create(campaign)`, `get(filter=None)`
- `create_session(campaign_id, session)`, `get_sessions(campaign_id, filter=None)`, `get_sessions_feedbacks(campaign_id, filter=None)`

### `client.metrics`
- `get(filter=None)`
- `kpi_ranking(company_id, dimension, formulas, start_date=None, end_date=None, integrations=None, products=None, min_responses=None, limit=None, filters=None, breakdown=None, compare_start_date=None, compare_end_date=None)` (since 1.0.26) — the KPIs the dashboards show, per value of a metric: one item per value of `dimension` (an agent, a team, a store...) with each KPI in `formulas` and the KPI of all of them together. See [KPIs per agent, team or store](#kpis-per-agent-team-or-store).

#### KPIs per agent, team or store

`kpi_ranking()` reads the same figures as the dashboard ranking, KPI and KPI-by-group widgets (`GET /metrics/insights/kpi-ranking`), so a report you build from it matches what your team sees on screen.

```python
agents = client.metrics.kpi_ranking(
    "YOUR_COMPANY_ID",
    dimension="agent",                 # the metric whose values you compare
    formulas=["csat", "nps"],          # the KPI metrics, by name
    start_date="2026-11-17",           # first and last day, both included
    end_date="2026-11-17",
)
for agent in agents:
    csat, nps = agent["kpis"]          # one per formula, in your order
    print(agent["value"], agent["total"], csat["kpi"], nps["kpi"])

overall = agents[0]["kpis"][0]["team_kpi"] if agents else None  # every agent together
```

- **Names.** `dimension` and `formulas` are metric names. `client.metrics.get({"where": {"companyId": "YOUR_COMPANY_ID"}})` lists your metrics; use each one's `metricName`. The KPIs are the metrics with `type` `FORMULA`.
- **Dates.** `start_date` and `end_date` are days (`"YYYY-MM-DD"` or a `date`), both included, in UTC, of the date the feedback happened (`externalGeneratedAt`). Leave them out for all dates.
- **Each item** has `value` (the agent, team... in lower case, as it is stored), `total` (its responses with any of the KPIs, each counted once) and `kpis`, with one entry per formula: `kpi` (`None` without responses), `total` (responses in that KPI), `promoters` and `detractors` (its positive and negative responses), `team_kpi` and `team_total` (the KPI and the responses of all values together, each feedback counted once), `delta` (`kpi - team_kpi`), `impact` (`delta * total / team_total`) and `higher_is_better`.
- **Order.** Best first, by the first KPI in `formulas` that has responses. `min_responses` leaves out the values with fewer responses in that KPI (they still count in the team), and `limit` keeps the first N.
- **Narrowing.** `integrations` and `products` take lists of IDs. `filters` keeps only the feedback with given metric values, e.g. `[{"name": "team", "values": ["north", "south"]}]`: a feedback must match every block and, in a block, any of its values; upper and lower case are the same.
- **Per integration.** `breakdown="integration"` adds a `breakdown` list to each item: its `total` and `kpis` in each integration, compared with the team of that integration.
- **Against another period.** `compare_start_date` and `compare_end_date` (both or neither) add `prev_kpi`, `prev_total` and `change` (`kpi - prev_kpi`) to each KPI.

The figures change when the dashboards' data is refreshed, so calling more often than that returns the same numbers. Parameters are URL-encoded, so names with spaces, accents or `&` are safe. Missing `company_id`, `dimension` or `formulas`, or only one comparison date, raises `ValueError` before any request; a company that is not yours is a **403** (`requests.HTTPError`).

### `client.dashboards`
- `get_data(dashboard_id, start_date=None, end_date=None)` (since 1.0.26) — a dashboard with what each of its widgets shows, as one dict (`GET /dashboard/{id}/data`): the same figures your team sees on screen, for the period and filters the dashboard opens on.

```python
doc = client.dashboards.get_data("YOUR_DASHBOARD_ID")   # the dashboard= value in its address
print(doc["period"])                                     # {"name": "Today", "startDate": ..., "endDate": ...}
for widget in doc["widgets"]:                            # top to bottom
    print(widget["title"], widget["type"], widget["data"])

# Another period instead of the dashboard's own (days, both included, UTC):
october = client.dashboards.get_data("YOUR_DASHBOARD_ID", start_date="2026-10-01", end_date="2026-10-31")
```

Each widget has `id`, `title`, `type`, `layout`, `config` and `data`, which is `None` for a widget whose data is not available this way. The KPI widgets give:

- `prefab.counter-kpi`: `formula`, `label`, `unit`, `dimension`, `kpi` and `total` (its responses).
- `prefab.kpi-ranking`: `dimension`, `kpis`, `reference` (every value together: its `kpi` and `total` per formula) and `rows`, every value with `rank`, `value`, `total`, `shown` (whether the dashboard displays it, e.g. the top 3) and its `kpis` (`kpi`, `delta` against the reference, `total`, `promoters`, `detractors`).
- `prefab.kpi-graph`: `formula`, `label`, `unit`, `dimension`, `average` and `rows` (`value`, `kpi`, `total`), in the chart's order.

Values such as agent names are in lower case, as they are stored. Your user's metric restrictions apply, as in Deepdots. A dashboard that doesn't exist or that you can't see is a **404**, another company's a **403** (`requests.HTTPError`).

### `client.products`
- `get(filter=None)`

### `client.companies`
- `get(filter=None)`, `get_id(id, filter=None)`

### `client.integrations_questions`
- `get(integration_id, filter=None)`

### `client.reports`
- `get(filter=None)`, `get_newsletter(filter=None)`, `update(report_id, report)`

### `client.requests`
- `get(filter=None)`, `get_id(request_id, filter=None)`, `update(request_id, request)`

To mark a request DONE/ERROR asynchronously, publish a completion event to the
`request-done` Pub/Sub topic (project `magicfeedback-prod-api`, topic
`request-done`); the `request-done` Cloud Function consumes it and PATCHes the
request. The SDK does not publish this itself — build the envelope with
`build_done_message` and publish it directly. See
[`examples/mark_request_done.py`](https://github.com/MagicFeedback/magicfeedback_python_sdk/blob/main/examples/mark_request_done.py).

## Examples

```python
# Create a feedback
client.feedbacks.create({
    "name": "Test Feedback",
    "type": "APP",
    "identity": "MAGICFORM",
    "integrationId": "your-integration-id",  # companyId and productId are taken from it
    "answers": [
        {"key": "score", "value": "4"},
        {"key": "comment", "value": "Great service!"},
    ],
    # Optional source-system fields: top level, see "Feedback source-system fields"
    "external_id": "48213",
    "externalGeneratedAt": "2026-10-06T11:00:00.000Z",
    "externalUrl": "https://forms.example.com/responses/48213",
})

# Get a feedback with its attachments
client.feedbacks.get_id(
    "<feedback_id>",
    filter={"include": [{"relation": "feedbackAttachments"}]}
)

# Upload a file attachment.
# A feedback holds at most 3 attachments, and a file whose bytes are identical
# to one already attached (even under a different name) is rejected with a
# ValueError — nothing is uploaded in either case.
client.feedbacks.upload_attachment(
    "<feedback_id>",
    file_path="/path/to/file.pdf",
    filename="report.pdf",              # optional, defaults to file name
    extra_data={"source": "crm"},       # optional, any JSON-serialisable dict
    # max_attachments=3,                # optional, override the per-feedback cap
    # check_duplicate_content=False,    # optional, skip the byte-for-byte dedupe
)

# Mark a request DONE via the request-done Pub/Sub topic.
# The SDK builds the envelope; the producer publishes it directly.
import json
from google.cloud import pubsub_v1
from magicfeedback_sdk.api.requests import build_done_message

message = build_done_message(
    "<request_id>",
    "<company_id>",
    output={"value": "…final result…"},
    sources=["<feedbackId1>", "<feedbackId2>"],  # optional
    logs="processed 2 items",                     # optional
    # success=False, error={"message": "processing failed"}  # to mark ERROR
)

publisher = pubsub_v1.PublisherClient()
topic_path = publisher.topic_path("magicfeedback-prod-api", "request-done")
publisher.publish(topic_path, json.dumps(message).encode("utf-8")).result()
```

## Logging

```python
import logging
client.set_logging(logging.DEBUG)
```

## License

MIT

## Contributing

Developing on the SDK itself — layout, tests, and how to cut a release — is
documented in [DEVELOPERS.md](https://github.com/MagicFeedback/magicfeedback_python_sdk/blob/main/DEVELOPERS.md).

## Contact

farias@magicfeedback.io
