karrio-server-core 2025.5__py3-none-any.whl

karrio/server/core/views/schema.py

@@ -0,0 +1,310 @@
+import jinja2
+import django.conf as django
+import drf_spectacular.views as views
+import rest_framework.response as response
+
+import django.urls as urls
+import karrio.server.conf as conf
+import karrio.server.core.dataunits as dataunits
+
+VERSION = getattr(django.settings, "VERSION", "")
+non_null = lambda items: [i for i in items if i is not None]
+RedocView = views.SpectacularRedocView.as_view(
+    url_name="shipping-openapi",
+    template_name="openapi/openapi.html",
+)
+
+
+class ShippingOpenAPIView(views.SpectacularAPIView):
+    def _get_schema_response(self, request):
+        version = (
+            self.api_version or request.version or self._get_version_parameter(request)
+        )
+        generator = self.generator_class(
+            urlconf=self.urlconf, api_version=version, patterns=self.patterns
+        )
+        data = generator.get_schema(request=request, public=self.serve_public)
+
+        data["tags"] = render_tags(request, conf.settings.APP_NAME)
+        data["components"]["securitySchemes"] = {
+            k: v
+            for k, v in data["components"]["securitySchemes"].items()
+            if k in ["JWT", "OAuth2", "Token", "TokenBasic"]
+        }
+        data["info"] = dict(
+            description=render_schema_description(conf.settings.APP_NAME),
+            title=f"{conf.settings.APP_NAME} API",
+            version=conf.settings.VERSION,
+        )
+
+        return response.Response(
+            data=data,
+            headers={
+                "Content-Disposition": f'inline; filename="{self._get_filename(request, version)}"'
+            },
+        )
+
+
+urlpatterns = [
+    urls.path(
+        django.settings.OPEN_API_PATH,
+        RedocView,
+        name="schema-rapi",
+    ),
+    urls.path(
+        "shipping-openapi",
+        ShippingOpenAPIView.as_view(),
+        name="shipping-openapi",
+    ),
+]
+
+
+def render_schema_description(APP_NAME):
+    return f"""
+{APP_NAME} is a multi-carrier shipping API that simplifies the integration of logistics carrier services.
+
+The {APP_NAME} API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded
+request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
+
+The {APP_NAME} API differs for every account as we release new versions.
+These docs are customized to your version of the API.
+
+
+## Versioning
+
+When backwards-incompatible changes are made to the API, a new, dated version is released.
+The current version is `{VERSION}`.
+
+Read our API changelog to learn more about backwards compatibility.
+
+As a precaution, use API versioning to check a new API version before committing to an upgrade.
+
+
+## Environments
+
+The {APP_NAME} API offer the possibility to create and retrieve certain objects in `test_mode`.
+In development, it is therefore possible to add carrier connections, get live rates,
+buy labels, create trackers and schedule pickups in `test_mode`.
+
+
+## Pagination
+
+All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list addresses,
+list shipments, and list trackers. These list API methods share a common structure, taking at least these
+two parameters: limit, and offset.
+
+{APP_NAME} utilizes offset-based pagination via the offset and limit parameters.
+Both parameters take a number as value (see below) and return objects in reverse chronological order.
+The offset parameter returns objects listed after an index.
+The limit parameter take a limit on the number of objects to be returned from 1 to 100.
+
+
+```json
+{{
+    "count": 100,
+    "next": "/v1/shipments?limit=25&offset=50",
+    "previous": "/v1/shipments?limit=25&offset=25",
+    "results": [
+        {{ ... }},
+    ]
+}}
+```
+
+## Metadata
+
+Updateable {APP_NAME} objects—including Shipment and Order have a metadata parameter.
+You can use this parameter to attach key-value data to these {APP_NAME} objects.
+
+Metadata is useful for storing additional, structured information on an object.
+As an example, you could store your user's full name and corresponding unique identifier
+from your system on a {APP_NAME} Order object.
+
+Do not store any sensitive information as metadata.
+
+## Authentication
+
+API keys are used to authenticate requests. You can view and manage your API keys in the Dashboard.
+
+Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret
+API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
+
+Authentication to the API is performed via HTTP Basic Auth. Provide your API token as
+the basic auth username value. You do not need to provide a password.
+
+```shell
+$ curl https://instance.api.com/v1/shipments \\
+    -u key_xxxxxx:
+# The colon prevents curl from asking for a password.
+```
+
+If you need to authenticate via bearer auth (e.g., for a cross-origin request),
+use `-H "Authorization: Token key_xxxxxx"` instead of `-u key_xxxxxx`.
+
+All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure).
+API requests without authentication will also fail.
+"""
+
+
+def render_reference_descriptions(request):
+    refs = dataunits.contextual_reference(request, reduced=False)
+
+    def format_preset(preset: dict):
+        vals = [
+            str(v)
+            for v in [
+                preset.get("width"),
+                preset.get("height"),
+                preset.get("length"),
+            ]
+            if v is not None
+        ]
+
+        return f'{" x ".join(vals)} {preset.get("dimension_unit").lower()}'
+
+    template = """## Carriers
+| Carrier Name | Display Name |
+| ------------ | ------------ |
+{% for carrier, name in refs.get("carriers", {}).items() -%}{% if carrier != "generic" -%}
+| {{ carrier }} | {{ name }} |
+{% endif -%}{% endfor %}
+---
+## Services
+The following service level codes can be used to reference specific rates
+when purchasing shipping labels using single call label creation.
+You can also find all of the possible service levels for each of your carrier
+accounts by using [this endpoint](#operation/&&get_services).
+{% for carrier, services in refs.get("services", {}).items() -%}{% if carrier != "generic" -%}
+### {{ refs.get("carriers", {}).get(carrier, "") }}
+| Code         | Service Name |
+| ------------ | ------------ |
+{% for code, name in services.items() -%}
+| {{ code }} | {{ name }} |
+{% endfor %}
+{% endif -%}{% endfor %}
+---
+## Parcel Templates
+Use any of the following templates when you ship with special carrier packaging.
+{% for carrier, presets in refs.get("package_presets", {}).items() -%}
+### {{ refs.get("carriers", {}).get(carrier, "") }}
+| Code         | Dimensions   |
+| ------------ | ------------ |
+{% for code, preset in presets.items() -%}
+| {{ code }} | {{ format_preset(preset) }} |
+{% endfor %}
+{% endfor %}
+"""
+
+    return jinja2.Template(template).render(refs=refs, format_preset=format_preset)
+
+
+def render_tags(request, APP_NAME):
+    return non_null(
+        [
+            {
+                "name": "API",
+                "description": """API instance metadata resources.
+                """,
+            },
+            {
+                "name": "Auth",
+                "description": """API authentication resources.
+                """,
+            },
+            {
+                "name": "Carriers",
+                "description": f"""This is an object representing your {APP_NAME} carrier extension.
+                You can retrieve all supported carrier extensions available.
+                """,
+            },
+            {
+                "name": "Connections",
+                "description": f"""This is an object representing your {APP_NAME} carrier connections.
+                You can retrieve all carrier connections available to your account.
+                The `carrier_id` is a friendly name you assign to your connection.
+                """,
+            },
+            {
+                "name": "Addresses",
+                "description": f"""This is an object representing your {APP_NAME} shipping address.
+                You can retrieve all addresses related to your {APP_NAME} account.
+                Address objects are linked to your shipment history, and can be used for recurring shipping
+                to / from the same locations.
+                """,
+            },
+            {
+                "name": "Parcels",
+                "description": f"""This is an object representing your {APP_NAME} shipping parcel.
+                Parcel objects are linked to your shipment history, and can be used for recurring shipping
+                using the same packaging.
+                """,
+            },
+            {
+                "name": "Shipments",
+                "description": f"""This is an object representing your {APP_NAME} shipment.
+                A Shipment guides you through process of preparing and purchasing a label for an order.
+                A Shipment transitions through multiple statuses throughout its lifetime as the package
+                shipped makes its journey to it's destination.
+                """,
+            },
+            {
+                "name": "Documents",
+                "description": f"""This is an object representing your {APP_NAME} document upload record.
+                A Document upload record keep traces of shipping trade documents uploaded to carriers
+                to fast track customs and border processing.
+                """,
+            },
+            {
+                "name": "Manifests",
+                "description": f"""This is an object representing your {APP_NAME} manifest details.
+                Some carriers require manifests to be created after labels are generated.
+                A manifest is a summary of all the shipments that are being sent out.
+                """,
+            },
+            {
+                "name": "Trackers",
+                "description": f"""This is an object representing your {APP_NAME} shipment tracker.
+                A shipment tracker is an object attached to a shipment by it's tracking number.
+                The tracker provide the latest tracking status and events associated with a shipment
+                """,
+            },
+            {
+                "name": "Pickups",
+                "description": f"""This is an object representing your {APP_NAME} pickup booking.
+                You can retrieve all pickup booked historically for your {APP_NAME} account shipments.
+                """,
+            },
+            {
+                "name": "Proxy",
+                "description": f"""In some scenarios, all we need is to send request to a carrier using the {APP_NAME} unified API.
+                The Proxy API comes handy for that as it turn {APP_NAME} into a simple middleware that converts and
+                validate your request and simply forward it to the shipping carrier server.<br/>
+                **Note:**<br/>
+                    When using the proxy API, no objects are created in the {APP_NAME} system.
+                    excpet API logs and tracing records for debugging purposes.
+                """,
+            },
+            {
+                "name": "Orders",
+                "description": f"""This is an object representing your {APP_NAME} order.
+                You can create {APP_NAME} orders to organize your shipments and ship line items separately.
+                """,
+            },
+            {
+                "name": "Webhooks",
+                "description": f"""This is an object representing your {APP_NAME} webhook.
+                You can configure webhook endpoints via the API to be notified about events happen in your
+                {APP_NAME} account.
+                """,
+            },
+            {
+                "name": "Batches",
+                "description": f"""This is an object representing your {APP_NAME} batch operation.
+                You can retrieve all batch operations historically for your {APP_NAME} account.
+                """,
+            },
+            {
+                "name": "Reference & Enums",
+                "description": render_reference_descriptions(request),
+            },
+        ]
+    )

karrio/server/filters/__init__.py

@@ -0,0 +1,2 @@
+from django_filters import *
+from karrio.server.filters.abstract import *

karrio/server/filters/abstract.py

@@ -0,0 +1,26 @@
+import django_filters
+import karrio.lib as lib
+
+
+class CharInFilter(django_filters.BaseInFilter, django_filters.CharFilter):
+    pass
+
+
+class FilterSet(django_filters.FilterSet):
+    def __init__(self, data=None, queryset=None, *, request=None, prefix=None):
+        data = {
+            **data,
+            **{
+                key: (
+                    ",".join(val)
+                    if self.base_filters.get(key).__class__ == CharInFilter
+                    else val
+                )
+                for key, val in data.items()
+            },
+        }
+        super().__init__(data, queryset, request=request, prefix=prefix)
+
+    def to_dict(self):
+        self.form.is_valid()
+        return lib.to_dict(self.form.cleaned_data)

karrio/server/iam/admin.py

@@ -0,0 +1,3 @@
+from django.contrib import admin
+
+# Register your models here.

karrio/server/iam/apps.py

@@ -0,0 +1,21 @@
+from django.apps import AppConfig
+from django.utils.translation import gettext_lazy as _
+
+
+class IamConfig(AppConfig):
+    name = "karrio.server.iam"
+    verbose_name = _("IAM")
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        from karrio.server.core import utils
+        from karrio.server.iam import signals, permissions
+
+        @utils.skip_on_commands()
+        def _init():
+            signals.register_all()
+
+            # Setup default permission groups and apply to existing orgs on start up
+            utils.run_on_all_tenants(permissions.setup_groups)()
+
+        _init()

karrio/server/iam/migrations/0001_initial.py

@@ -0,0 +1,33 @@
+# Generated by Django 3.2.14 on 2022-09-03 12:25
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('user', '0004_group'),
+        ('auth', '0012_alter_user_first_name_max_length'),
+        ('contenttypes', '0002_remove_content_type_name'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='ContextPermission',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')),
+                ('object_pk', models.CharField(db_index=True, max_length=50, verbose_name='object pk')),
+                ('content_type', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='+', to='contenttypes.contenttype', verbose_name='content type')),
+                ('groups', models.ManyToManyField(blank=True, help_text='The groups this user context belongs to. A user will get all permissions granted to each of their groups.', related_name='context', related_query_name='context', to='user.Group', verbose_name='groups')),
+                ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user context.', related_name='context', related_query_name='context', to='auth.Permission', verbose_name='user context permissions')),
+            ],
+            options={
+                'verbose_name': 'context permission',
+                'verbose_name_plural': 'context permission',
+            },
+        ),
+    ]

karrio/server/iam/models.py

@@ -0,0 +1,48 @@
+from django.db import models
+from django.contrib.auth.models import PermissionsMixin, Permission
+from django.contrib.contenttypes.fields import GenericForeignKey
+from django.utils.translation import gettext_lazy as _
+
+import karrio.server.user.models as user
+
+User = user.User
+Group = user.Group
+
+
+class ContextPermission(PermissionsMixin):
+    class Meta:
+        verbose_name = _("context permission")
+        verbose_name_plural = _("context permission")
+
+    def __str__(self) -> str:
+        return f"{self.object_pk} - {self.content_type}"
+
+    content_type = models.ForeignKey(
+        to="contenttypes.ContentType",
+        on_delete=models.CASCADE,
+        related_name="+",
+        verbose_name=_("content type"),
+    )
+    object_pk = models.CharField(
+        db_index=True, max_length=50, verbose_name=_("object pk")
+    )
+    content_object = GenericForeignKey("content_type", "object_pk")
+    groups = models.ManyToManyField(
+        Group,
+        verbose_name=_("groups"),
+        blank=True,
+        help_text=_(
+            "The groups this user context belongs to. A user will get all permissions "
+            "granted to each of their groups."
+        ),
+        related_name="context",
+        related_query_name="context",
+    )
+    user_permissions = models.ManyToManyField(
+        Permission,
+        verbose_name=_("user context permissions"),
+        blank=True,
+        help_text=_("Specific permissions for this user context."),
+        related_name="context",
+        related_query_name="context",
+    )

karrio/server/iam/permissions.py

@@ -0,0 +1,155 @@
+import typing
+from django.db import models
+from django.contrib.auth import get_user_model
+from django.contrib.auth.models import Permission
+from karrio.server.core.logging import logger
+
+import karrio.server.core.utils as utils
+import karrio.server.user.models as users
+import karrio.server.iam.serializers as serializers
+
+User = get_user_model()
+
+
+@utils.skip_on_loadata
+@utils.async_wrapper
+@utils.tenant_aware
+def setup_groups(**_):
+    """This function create all standard group permissions if they don't exsist."""
+    logger.info("Setting up permissions")
+
+    # manage_apps
+    setup_group(
+        serializers.PermissionGroup.manage_apps.name,
+        permissions=Permission.objects.filter(content_type__app_label="apps"),
+    )
+
+    # manage_carriers (deprecated - kept for backward compatibility)
+    setup_group(
+        serializers.PermissionGroup.manage_carriers.name,
+        permissions=[
+            *Permission.objects.filter(content_type__app_label="providers"),
+            *Permission.objects.filter(
+                models.Q(content_type__app_label="orgs")
+                & models.Q(name__icontains="carrier")
+            ),
+        ],
+        override=True,
+    )
+
+    # read_carriers (view permissions only)
+    setup_group(
+        serializers.PermissionGroup.read_carriers.name,
+        permissions=Permission.objects.filter(
+            content_type__app_label="providers", name__icontains="view"
+        ),
+        override=True,
+    )
+
+    # write_carriers (create, update, delete permissions)
+    setup_group(
+        serializers.PermissionGroup.write_carriers.name,
+        permissions=[
+            *Permission.objects.filter(content_type__app_label="providers"),
+            *Permission.objects.filter(
+                models.Q(content_type__app_label="orgs")
+                & models.Q(name__icontains="carrier")
+            ),
+        ],
+        override=True,
+    )
+
+    # manage_orders
+    setup_group(
+        serializers.PermissionGroup.manage_orders.name,
+        permissions=Permission.objects.filter(content_type__app_label="orders"),
+    )
+
+    # manage_team
+    setup_group(
+        serializers.PermissionGroup.manage_team.name,
+        permissions=(
+            Permission.objects.filter(
+                content_type__app_label="orgs", name__icontains="organization"
+            ).exclude(name__icontains="owner")
+        ),
+        override=True,
+    )
+
+    # manage_org_owner
+    setup_group(
+        serializers.PermissionGroup.manage_org_owner.name,
+        permissions=Permission.objects.filter(
+            content_type__model="OrganizationOwner".lower()
+        ),
+    )
+
+    # manage_webhooks
+    setup_group(
+        serializers.PermissionGroup.manage_webhooks.name,
+        permissions=Permission.objects.filter(content_type__model="Webhook".lower()),
+    )
+
+    # manage_data
+    setup_group(
+        serializers.PermissionGroup.manage_data.name,
+        permissions=[
+            *Permission.objects.filter(
+                content_type__app_label__in=["data", "graph", "documents"]
+            ),
+            *Permission.objects.filter(
+                content_type__app_label="audit", name__icontains="view"
+            ),
+            *Permission.objects.filter(
+                content_type__app_label="rest_framework_tracking",
+                name__icontains="view",
+            ),
+        ],
+        override=True,
+    )
+
+    # manage_shipments
+    setup_group(
+        serializers.PermissionGroup.manage_shipments.name,
+        permissions=[
+            *Permission.objects.filter(content_type__app_label="manager"),
+            *Permission.objects.filter(
+                models.Q(content_type__app_label="orgs")
+                & (
+                    models.Q(name__icontains="address")
+                    | models.Q(name__icontains="parcel")
+                    | models.Q(name__icontains="commodity")
+                    | models.Q(name__icontains="customs")
+                    | models.Q(name__icontains="pickup")
+                    | models.Q(name__icontains="tracker")
+                    | models.Q(name__icontains="shipment")
+                )
+            ),
+        ],
+    )
+
+    # manage_system
+    setup_group(
+        serializers.PermissionGroup.manage_system.name,
+        permissions=Permission.objects.filter(
+            content_type__app_label__in=[
+                "admin",
+                "user",
+                "pricing",
+                "providers",
+                "audit",
+                "database",
+                "rest_framework_tracking",
+            ]
+        ),
+    )
+
+
+def setup_group(
+    name: str, permissions: typing.List[Permission], override: bool = False
+):
+    group, created = users.Group.objects.get_or_create(name=name)
+
+    if created or override:
+        group.permissions.set(permissions)
+        group.save()

karrio/server/iam/serializers.py

@@ -0,0 +1,54 @@
+import typing
+import karrio.lib as lib
+
+
+class PermissionGroup(lib.StrEnum):
+    manage_apps = "manage_apps"
+    manage_team = "manage_team"
+    manage_system = "manage_system"
+    manage_orders = "manage_orders"
+    manage_data = "manage_data"
+    manage_pickups = "manage_pickups"
+    manage_carriers = "manage_carriers"  # Deprecated: use read_carriers + write_carriers
+    read_carriers = "read_carriers"
+    write_carriers = "write_carriers"
+    manage_trackers = "manage_trackers"
+    manage_webhooks = "manage_webhooks"
+    manage_shipments = "manage_shipments"
+    manage_org_owner = "manage_org_owner"
+
+
+PERMISSION_GROUPS = [(p.name, p.name) for p in list(PermissionGroup)]
+ROLES_GROUPS: typing.Dict[str, typing.List[str]] = {
+    "owner": [
+        PermissionGroup.manage_org_owner.value,
+        PermissionGroup.manage_team.value,
+        PermissionGroup.manage_apps.value,
+        PermissionGroup.read_carriers.value,
+        PermissionGroup.write_carriers.value,
+        PermissionGroup.manage_webhooks.value,
+        PermissionGroup.manage_data.value,
+        PermissionGroup.manage_orders.value,
+        PermissionGroup.manage_pickups.value,
+        PermissionGroup.manage_trackers.value,
+        PermissionGroup.manage_shipments.value,
+    ],
+    "admin": [
+        PermissionGroup.manage_team.value,
+        PermissionGroup.manage_apps.value,
+        PermissionGroup.read_carriers.value,
+        PermissionGroup.write_carriers.value,
+    ],
+    "developer": [
+        PermissionGroup.manage_webhooks.value,
+        PermissionGroup.read_carriers.value,
+    ],
+    "member": [
+        PermissionGroup.manage_data.value,
+        PermissionGroup.manage_orders.value,
+        PermissionGroup.manage_pickups.value,
+        PermissionGroup.manage_trackers.value,
+        PermissionGroup.manage_shipments.value,
+        PermissionGroup.read_carriers.value,
+    ],
+}

karrio/server/iam/signals.py

@@ -0,0 +1,18 @@
+from django.db.models import signals
+
+from karrio.server.core.logging import logger
+import karrio.server.core.utils as utils
+import karrio.server.user.models as user
+import karrio.server.iam.models as models
+
+
+def register_all():
+    signals.post_delete.connect(context_object_deleted, sender=user.Token)
+
+    logger.info("Signal registration complete", module="karrio.iam")
+
+
+@utils.disable_for_loaddata
+def context_object_deleted(sender, instance, *args, **kwargs):
+    # clean up permission contexts when related objects are removed.
+    models.ContextPermission.objects.filter(object_pk=instance.pk).delete()

karrio/server/iam/tests.py

@@ -0,0 +1,3 @@
+from django.test import TestCase
+
+# Create your tests here.