@deliverart/sdk-js-integration 0.0.0-dev-20260721002647

package/README.md

@@ -0,0 +1,282 @@
+# @deliverart/sdk-js-integration
+
+Integration management package for the DeliverArt JavaScript SDK.
+
+## Installation
+
+```bash
+npm install @deliverart/sdk-js-integration @deliverart/sdk-js-core
+```
+
+## Exported Types
+
+### Core Types
+- `Integration` - Integration configuration
+- `ActivatableIntegration` - Integration that can be activated/deactivated
+- `IntegrationActivationRequest` - Request to activate an integration
+- `IntegrationCancellationRequest` - Request to cancel an integration
+
+### Integration Types
+Integration types vary by service (delivery partners, payment gateways, etc.)
+
+The ecommerce info payload exposes the cached menu DTO. Item entries include
+`compositions`, the ids of removable base ingredients/components to send as
+writable order item `removals`.
+It also exposes the POS `currency` on both the top-level ecommerce info payload
+and `pointOfSale`, so storefronts can format menu prices, totals, payment
+summaries, and order history without assuming EUR.
+
+### IRI Types
+- `IntegrationIri` - Integration IRI (`/integrations/:id`)
+- `ActivationRequestIri` - Activation request IRI
+- `CancellationRequestIri` - Cancellation request IRI
+
+## Available Requests
+
+### GetIntegrations
+Get list of available integrations.
+
+```typescript
+import { GetIntegrations } from '@deliverart/sdk-js-integration';
+
+const integrations = await sdk.call(new GetIntegrations({
+  query: {
+    company: '/companies/123',
+    type: 'DELIVERY'
+  }
+}));
+```
+
+---
+
+### GetIntegrationDetails
+Get detailed information about an integration.
+
+```typescript
+import { GetIntegrationDetails } from '@deliverart/sdk-js-integration';
+
+const integration = await sdk.call(new GetIntegrationDetails('integration-123'));
+```
+
+---
+
+### ActivateIntegration
+Request activation of an integration.
+
+```typescript
+import { ActivateIntegration } from '@deliverart/sdk-js-integration';
+
+const activation = await sdk.call(new ActivateIntegration({
+  integration: '/integrations/123',
+  pointOfSale: '/point_of_sales/456',
+  config: {
+    apiKey: 'your-api-key',
+    // ... integration-specific config
+  }
+}));
+```
+
+---
+
+### CancelIntegration
+Request cancellation of an active integration.
+
+```typescript
+import { CancelIntegration } from '@deliverart/sdk-js-integration';
+
+const cancellation = await sdk.call(new CancelIntegration({
+  integration: '/integrations/123',
+  reason: 'No longer needed'
+}));
+```
+
+---
+
+### Deliveroo Manual Portal Activation
+
+Deliveroo integrations expose `manualActivationCompleted` and `manualActivationCompletedAt` so operator tools can track whether the final manual activation step has been completed in the Deliveroo portal.
+
+```typescript
+import {
+  GetIntegrationDeliverooList,
+  UpdateIntegrationDeliveroo,
+} from '@deliverart/sdk-js-integration';
+
+const pending = await sdk.call(new GetIntegrationDeliverooList({
+  query: {
+    manualActivationCompleted: false,
+  },
+}));
+
+await sdk.call(new UpdateIntegrationDeliveroo('deliveroo-integration-id', {
+  manualActivationCompleted: true,
+}));
+```
+
+---
+
+### Elephant Integrations
+
+Elephant uses one integration per point of sale and one or more nested Restaurant
+memberships. Create the integration first, then provision each Restaurant with its
+Deliverart sales mode, fallback category, catalog channels, order type, preparation
+time, and acceptance timeout.
+
+```typescript
+import {
+  CreateIntegrationElephantRestaurantMapping,
+  CreateIntegrationElephant,
+  CreateIntegrationElephantRestaurant,
+  GetIntegrationElephantOrderReleases,
+  GetIntegrationElephantRestaurantCatalogProducts,
+  GetIntegrationElephantRestaurantMappings,
+  GetIntegrationElephantRestaurants,
+  GetIntegrationRequestLogs,
+  RefreshIntegrationElephantRestaurantCatalog,
+  RetryIntegrationElephantProvisioning,
+  UpdateIntegrationElephant,
+  UpdateIntegrationElephantRestaurant,
+} from '@deliverart/sdk-js-integration';
+
+const integration = await sdk.call(new CreateIntegrationElephant({
+  pointOfSale: '/point_of_sales/8a745a0b-a68b-4f98-87ca-74df04a3bfe3',
+  credentialMode: 'managed',
+}));
+
+const restaurant = await sdk.call(new CreateIntegrationElephantRestaurant(integration.id, {
+  name: 'Restaurant Centre',
+  platform: 'yengec',
+  platformRestaurantId: 'restaurant-123',
+  authentication: { apiKey: 'write-only-platform-key' },
+  salesMode: '/sales_modes/a1538842-0931-4e23-8aaf-5bda59198581',
+  category: '/menu_item_categories/20c71a6a-c924-42e0-9078-e3f672704dbb',
+  defaultTaxRate: 10,
+  channels: ['application', 'elephant'],
+  orderType: 'delivery',
+  defaultPreparationTime: 15,
+  acceptanceTimeout: 5,
+}));
+
+await sdk.call(new UpdateIntegrationElephant(integration.id, {
+  defaultRestaurantMembership: `/integrations/elephant/${integration.id}/restaurants/${restaurant.id}`,
+}));
+
+await sdk.call(new UpdateIntegrationElephantRestaurant(integration.id, restaurant.id, {
+  acceptanceTimeout: 10,
+}));
+
+const staleRestaurants = await sdk.call(new GetIntegrationElephantRestaurants(integration.id, {
+  query: {
+    catalogStatus: 'stale',
+    status: ['active', 'paused'],
+    'order[name]': 'asc',
+  },
+}));
+
+await sdk.call(new RetryIntegrationElephantProvisioning(integration.id));
+await sdk.call(new RefreshIntegrationElephantRestaurantCatalog(integration.id, restaurant.id));
+
+const platformProducts = await sdk.call(
+  new GetIntegrationElephantRestaurantCatalogProducts(integration.id, restaurant.id, {
+    query: { q: 'pizza', page: 1 },
+  }),
+);
+const mappings = await sdk.call(
+  new GetIntegrationElephantRestaurantMappings(integration.id, restaurant.id, {
+    query: { role: 'product', page: 1 },
+  }),
+);
+
+await sdk.call(new CreateIntegrationElephantRestaurantMapping(integration.id, restaurant.id, {
+  role: 'product',
+  platformReference: platformProducts.data[0].platformReference!,
+  platformGroupReference: null,
+  appMenuItemId: 'deliverart-menu-item-id',
+  appModifierId: null,
+  appVariantId: null,
+  appSalesModeId: null,
+}));
+
+const releases = await sdk.call(new GetIntegrationElephantOrderReleases(integration.id, {
+  query: { status: ['preparing', 'failed'], page: 1 },
+}));
+const requestLogs = await sdk.call(new GetIntegrationRequestLogs(integration.id, {
+  query: { outcome: 'server_error', page: 1 },
+}));
+```
+
+Use `credentialMode: 'provided'` only when attaching an existing Elephant Tenant and
+App; `tenantId`, `appId`, and `personalAccessToken` are then all required. Restaurant
+authentication is write-only. Deleting a Restaurant membership starts its asynchronous
+`removing` lifecycle; the Elephant integration itself does not expose a direct DELETE
+operation.
+
+The following request classes cover the current API surface:
+
+- `GetIntegrationElephantList`, `GetIntegrationElephantDetails`
+- `CreateIntegrationElephant`, `UpdateIntegrationElephant`
+- `GetIntegrationElephantRestaurants`, `GetIntegrationElephantRestaurantDetails`
+- `CreateIntegrationElephantRestaurant`, `UpdateIntegrationElephantRestaurant`
+- `DeleteIntegrationElephantRestaurant`
+- `RetryIntegrationElephantProvisioning`, `TestIntegrationElephantConnection`,
+  `ReconcileIntegrationElephant`
+- `RetryIntegrationElephantRestaurantProvisioning`,
+  `TestIntegrationElephantRestaurantConnection`,
+  `RefreshIntegrationElephantRestaurantCatalog`,
+  `PauseIntegrationElephantRestaurant`, `ResumeIntegrationElephantRestaurant`
+- `GetIntegrationElephantRestaurantCatalogProducts`,
+  `GetIntegrationElephantRestaurantCatalogOptions`,
+  `GetIntegrationElephantRestaurantCatalogVariants`,
+  `GetIntegrationElephantRestaurantAppCatalogMirror`
+- `GetIntegrationElephantRestaurantMappings`,
+  `CreateIntegrationElephantRestaurantMapping`,
+  `DeleteIntegrationElephantRestaurantMapping`
+- `GetIntegrationElephantOrderReleases`, `GetIntegrationElephantOrderReleaseDetails`
+- `GetIntegrationRequestLogs`, `GetIntegrationRequestLogDetails`
+
+Catalog, mapping, Restaurant, order-release, and request-log collections are paginated.
+Use their exported query types rather than constructing query strings manually. Request logs
+are the API's sanitized diagnostics model: tokens and payload bodies are deliberately absent.
+
+---
+
+## Complete Usage Example
+
+```typescript
+import { sdk } from './lib/sdk';
+import {
+  GetIntegrations,
+  ActivateIntegration,
+  CancelIntegration
+} from '@deliverart/sdk-js-integration';
+
+async function integrationManagement() {
+  // Get available delivery integrations
+  const integrations = await sdk.call(new GetIntegrations({
+    query: {
+      type: 'DELIVERY',
+      company: '/companies/123'
+    }
+  }));
+
+  // Activate delivery partner
+  const activation = await sdk.call(new ActivateIntegration({
+    integration: integrations.data[0]['@id'],
+    pointOfSale: '/point_of_sales/456',
+    config: {
+      apiKey: process.env.DELIVERY_API_KEY,
+      webhookUrl: 'https://myapp.com/webhooks/delivery'
+    }
+  }));
+
+  // Cancel integration
+  await sdk.call(new CancelIntegration({
+    integration: activation.integration,
+    reason: 'Switching to different provider'
+  }));
+}
+```
+
+## License
+
+MIT