Changelog

• load_xarray() and load_dataframe() now raise SubscriptionFailedError when the subscription's status is failed, instead of warning and returning an empty-looking result. failed is terminal, so there is nothing to load; the error message carries the subscription ID and the provider's own explanation from status_message (or "The provider returned no detail." when none was given). pending, processing and partial subscriptions still emit the UserWarning introduced in 0.1.19 and return the data that exists. Catch cecil.errors.SubscriptionFailedError (a subclass of cecil.errors.Error) if your code loads subscriptions whose status you have not checked.

• Added status and status_message to the Subscription model. status is one of pending (created, no data yet), processing (data arriving), completed (everything the dataset should have by now is delivered; later time steps such as a new quarter still arrive as appends), partial (some data landed but the subscription will not complete) or failed (no usable data). status_message is None unless there is something to say — the provider's own error text, or how long the pipeline has been quiet. Both are None on API responses that predate the field.
• load_xarray() and load_dataframe() now emit a UserWarning when the subscription's status is not completed, so a valid-looking but incomplete dataset (for example 2 of 20 variables a few minutes after creation) is no longer silent. Nothing is raised; the data is returned as before.
• create_webhook() accepts an optional events list to choose which event types the webhook receives: subscription.delivered, subscription.failed, subscription.completed. Omit it to receive all three. Existing webhooks keep receiving delivered and failed only; recreate one with events to add completed. The Webhook model gains events.

• Added dataset_publication and dataset_current_publication to the Subscription model. dataset_publication is the publication of the dataset your subscription was created under and never changes; dataset_current_publication is the dataset's publication now. When the two differ, a newer publication exists and you can create a new subscription to pick it up (create_subscription(..., allow_duplicate=True)). Both are None for subscriptions the API has not pinned.
• load_xarray() and load_dataframe() now attach both values to the returned object's .attrs, next to dataset_id and subscription_id. This adds one lightweight request per load. Note that pandas .attrs does not survive every DataFrame operation; the Subscription returned by get_subscription() is the source of truth.

• Fixed load_xarray() failing with ValueError: cannot convert float NaN to integer when a dataset declares an integer band with no nodata value (first seen on Biomass Atlas computed). Such bands are now returned without a _FillValue; every stored value is data. Float bands without a declared nodata still default to NaN, and bands with a declared nodata are unchanged. Biomass Atlas users should upgrade to this version to use load_xarray().

• create_subscription() no longer silently creates a duplicate: if you already have an active subscription for the same AOI and dataset, the API returns an error naming the existing subscription, raised as cecil.errors.DuplicateSubscriptionError. Pass the new allow_duplicate=True parameter to create one deliberately (for example, to pick up a new dataset version), or archive the old subscription first.
• create_aoi() with a geometry identical to one of your existing AOIs now returns the existing AOI instead of creating a duplicate, so re-running a registration script converges on the same IDs. Passing a different external_ref still creates a separate AOI.
• Added optional scale and offset to the dataset Variable model: variables whose stored values are packed now expose the packing in dataset metadata (get_dataset()/list_datasets()), matching the dataset pages.

• Widened the pyarrow dependency range to allow 23.x (previously pinned below 23), so new installs pick up pyarrow 23.0.1, which includes a high-severity security fix. Upgrading is recommended but not required — no SDK behaviour changes.

• Added get_usage(): your organisation's subscription and AOI counts and subscribed hectares, all-time and for the current calendar month, alongside the monthly subscription limit (and, for unverified organisations, the account caps). Requires the corresponding API release.

• Improved load_dataframe() performance for self-hosted datasets: the parquet footer is now read once per file instead of twice (up to ~3s faster per call on wide datasets).
• Added optional columns parameter to load_dataframe() to load a subset of columns (self-hosted datasets only); geometry is always included.
• load_xarray() now applies scale_factor/add_offset for bands that declare them in the dataset file schema: values are returned as physical float32 with NaN nodata, and the packing metadata moves to each variable's .encoding. Pass mask_and_scale=False to get raw packed values with the true scale_factor/add_offset as attributes instead. Bands without a declared scale/offset are unaffected.
• Fixed load_xarray() stamping the first file's scale_factor/add_offset attributes onto every variable; variables without a declared scale/offset no longer carry these attributes.
• Added geometry_type and location_count to the AOI model (returned by the API since 2026-08-20).

• Improves load_dataframe() compatibility with more vector dataset types across different coordinate reference systems.

• Changed load_dataframe() to return GeoDataframe format.
• Upgraded Python required version to 3.11.

• Added get_dataset().
• Added all details to Dataset.
• Improved error handling.
• Made external_ref nullable for Subscription and AOI.
• Renamed get_organisation_settings() to get_settings().
• Renamed update_organisation_settings() to update_settings().

• Changed load_dataframe() to retry when failing to load files from bucket.

Webhook improvements

• Added list_webhooks().
• Added get_webhook().
• Renamed webhook_configure() to create_webhook().
• Changed delete_webhook() to receive an id param.

Archive/restore AOI

• Added archive_aoi().
• Added restore_aoi().
• Changed list_aois() to accept an optional archived param.

Archive/restore subscription

• Added archive_subscription().
• Added restore_subscription() within the grace period.
• Changed list_subscriptions() to accept an optional archived param.

• Added configure_webhook().
• Added delete_webhook().
• Added HTTPError and SDKError.
• Improved error handling.

• Added list_datasets().

• Changed load_dataframe() to reset dataframe index after concatenation.

• Updated error handling to handle HTTP 403 Forbidden errors.

• Renamed AOIRecord to AOI.

• Changed load_dataframe() to return empty dataframe when no data is available.

• Updated dependencies.

• First release.