@widgetic/api-contracts 1.11.115 → 1.11.127

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/metadata.json CHANGED
@@ -1,16 +1,16 @@
1
1
  {
2
2
  "package": "@widgetic/api-contracts",
3
- "version": "1.11.115",
3
+ "version": "1.11.127",
4
4
  "publishTag": "latest",
5
5
  "source": {
6
- "commit": "e989e1fc7db88bff337ff44ee5d93a494247cefb",
6
+ "commit": "bc6f558c13283761dd938bc8338cdfc8a874679f",
7
7
  "branch": null,
8
8
  "dirty": false,
9
9
  "atOriginMain": true
10
10
  },
11
11
  "openApi": {
12
12
  "file": "openapi-public.json",
13
- "sha256": "08fb0fbbdefbe4374524870d725f69409cbadf90b2bf70f2421963a29b0b93c8",
13
+ "sha256": "3f2012956a562333734e0d22900b600fa8cecb1a398eb7f9921f5ff3b7a31df2",
14
14
  "paths": 124,
15
15
  "operations": 169,
16
16
  "servers": [
@@ -3761,7 +3761,7 @@
3761
3761
  "get": {
3762
3762
  "operationId": "getWorkspaceWorkflowStats",
3763
3763
  "summary": "Get what Visitors Did in a Workflow",
3764
- "description": "Counts per block and per connection over a range of UTC days (the last 30 days when not given, up to 366), for one\nversion or for all of them. Only counts: how many visitors reached a block, took a connection, or could not be\nmoved on. No visitor and no value a visitor typed is ever stored.\nFor personal workspace, use 'personal' as workspaceId.\nFor organization workspace, use the organization UUID as workspaceId. Any active member can read.\n",
3764
+ "description": "Counts per block and per connection over a range of UTC days (the last 30 days when not given, up to 366), for one\nversion or for all of them. Only counts: how many visitors reached a block, took a connection, or could not be\nmoved on, and, where the visitor's browser said why a block could not be shown, how many of those failures had each\nreason (`failedReasons`: a timeout, an error of the widget, a build that failed, or another reason). No visitor and\nno value a visitor typed is ever stored.\nFor personal workspace, use 'personal' as workspaceId.\nFor organization workspace, use the organization UUID as workspaceId. Any active member can read.\n",
3765
3765
  "tags": [
3766
3766
  "Workflows"
3767
3767
  ],
@@ -5634,12 +5634,12 @@
5634
5634
  },
5635
5635
  "/uploads": {
5636
5636
  "post": {
5637
- "operationId": "uploadsPost",
5637
+ "operationId": "uploadFile",
5638
5638
  "tags": [
5639
5639
  "Uploads"
5640
5640
  ],
5641
5641
  "summary": "Upload a file",
5642
- "description": "Stores one file for the account and returns its public address. This is how a user's own images,\nvideo and PDFs reach a widget's content.\n\nSend a `multipart/form-data` request with the file in the field named `file`. The file counts\nagainst the storage of the workspace it is uploaded in, and a full workspace is refused with 413 and\n`QUOTA_STORAGE_EXCEEDED`. For a person signed in on widgetic.com that is the workspace they are currently\nworking in: inside a team, the team's shared storage; inside their own workspace, their own allowance. An\norganization API key, and a Shopify store's session, always work in that team's shared storage. A personal\nAPI key or an SDK token always uses the account's own allowance. The two never add up and one never lends\nroom to the other. A file over the size limit is refused with 413 and `UPLOAD_TOO_LARGE`, and a\ntype that is not accepted with 415 and `UPLOAD_UNSUPPORTED_TYPE`; `uploadsLimitsGet` lists the size\nlimit and the accepted types.\n\nA file is judged by what is in it, not by the type it is sent as. A file that is not the type it claims (a\nweb page sent as `image/png`) is refused with 415 and `UPLOAD_UNSUPPORTED_TYPE`, and a picture sent under\nthe wrong picture type is stored under the type it really is, which `mime_type` in the answer says. An SVG\nis rewritten as it is stored: script, `foreignObject`, animation and references to other addresses are\ntaken out, it must be UTF-8 and at most 2 MB, and the stored file can be larger or smaller than the one\nsent. Anything that is not an image, audio or video (a PDF, for example) is served as a download rather\nthan shown in a page.\n\nWhen the full storage is a Shopify store's team's, extra storage cannot be added through Shopify yet, so the\nmessage ends by saying so and what to do instead: delete files, or contact support. On a Solo plan it names\nthe Teams plan (which holds more) and `error.details.planPageUrl` is the address of the plan page on Shopify.\n`error.suggestedAction` says the same in a few words, instead of the usual \"upgrade your storage plan\". Any\nother team, and a person's own workspace, get the shorter message.\n\nTo upload the file for one of your managed users, send `managedUserId` (Widgetic's id for the user) or\n`managedUserExternalId` (your own identifier for the user), not both. The file stays in your account and\ncounts against its allowance; the tag lets you list one user's files with `uploadsGet`. The managed user\nmust be yours and active: one that is not yours, or does not exist, is refused with 404 and\n`MANAGED_USER_NOT_FOUND`, and one that is switched off with 409 and `MANAGED_USER_INACTIVE`, before the\nfile is stored. The tag is set here and does not change afterwards.\n\nCalled with an editor session (`createManagedUserEditorSession`), the file is always filed for the\nsession's own managed user and is always media for widget content: naming another managed user is\nrefused with 403 and `MANAGED_USER_SESSION_MISMATCH`, and `contextType`, `source`, `widgetId` and\n`conversationId` are ignored. A full storage allowance is refused with the same 413 and\n`QUOTA_STORAGE_EXCEEDED`, but the message only says that it is not available right now (not how much is\nstored: that is the partner's business) and `error.details.limit` is `storage`.\n\nAn account that administers a partner with a storage destination (`setPartnerStorageDestination`) has\nits files stored in the partner's own bucket instead. Such a file takes none of the allowance, its `url`\nis served from the partner's public address, and its `storage_key` is the key in the partner's bucket.\nThe file is never stored with Widgetic instead: when the destination cannot be used the upload is refused\nwith 503 and `STORAGE_DESTINATION_UNAVAILABLE`, and when the partner's storage rejects the file with\n502 and `STORAGE_DESTINATION_WRITE_FAILED`.\n\nPartner storage is not optional, and it does not depend on how the file arrives. A partner's own uploads (with\nits API key, an SDK token, or from the Widgetic website, the resumable route and the media library alike)\nand the uploads of its customers' editor sessions are kept in the partner's own storage or not at all, so a\npartner with no destination (or one that removed it after the session was made) has them refused with 409\nand `PARTNER_STORAGE_REQUIRED`; they are never stored with Widgetic. An editor session's browser is only\ntold that the feature is not available right now.\n",
5642
+ "description": "Stores one file for the account and returns its public address. This is how a user's own images,\nvideo and PDFs reach a widget's content.\n\nSend a `multipart/form-data` request with the file in the field named `file`. The file counts\nagainst the storage of the workspace it is uploaded in, and a full workspace is refused with 413 and\n`QUOTA_STORAGE_EXCEEDED`. For a person signed in on widgetic.com that is the workspace they are currently\nworking in: inside a team, the team's shared storage; inside their own workspace, their own allowance. An\norganization API key, and a Shopify store's session, always work in that team's shared storage. A personal\nAPI key or an SDK token always uses the account's own allowance. The two never add up and one never lends\nroom to the other. A file over the size limit is refused with 413 and `UPLOAD_TOO_LARGE`, and a\ntype that is not accepted with 415 and `UPLOAD_UNSUPPORTED_TYPE`; `getUploadLimits` lists the size\nlimit and the accepted types.\n\nA file is judged by what is in it, not by the type it is sent as. A file that is not the type it claims (a\nweb page sent as `image/png`) is refused with 415 and `UPLOAD_UNSUPPORTED_TYPE`, and a picture sent under\nthe wrong picture type is stored under the type it really is, which `mime_type` in the answer says. An SVG\nis rewritten as it is stored: script, `foreignObject`, animation and references to other addresses are\ntaken out, it must be UTF-8 and at most 2 MB, and the stored file can be larger or smaller than the one\nsent. Anything that is not an image, audio or video (a PDF, for example) is served as a download rather\nthan shown in a page.\n\nWhen the full storage is a Shopify store's team's, extra storage cannot be added through Shopify yet, so the\nmessage ends by saying so and what to do instead: delete files, or contact support. On a Solo plan it names\nthe Teams plan (which holds more) and `error.details.planPageUrl` is the address of the plan page on Shopify.\n`error.suggestedAction` says the same in a few words, instead of the usual \"upgrade your storage plan\". Any\nother team, and a person's own workspace, get the shorter message.\n\nTo upload the file for one of your managed users, send `managedUserId` (Widgetic's id for the user) or\n`managedUserExternalId` (your own identifier for the user), not both. The file stays in your account and\ncounts against its allowance; the tag lets you list one user's files with `listUploads`. The managed user\nmust be yours and active: one that is not yours, or does not exist, is refused with 404 and\n`MANAGED_USER_NOT_FOUND`, and one that is switched off with 409 and `MANAGED_USER_INACTIVE`, before the\nfile is stored. The tag is set here and does not change afterwards.\n\nCalled with an editor session (`createManagedUserEditorSession`), the file is always filed for the\nsession's own managed user and is always media for widget content: naming another managed user is\nrefused with 403 and `MANAGED_USER_SESSION_MISMATCH`, and `contextType`, `source`, `widgetId` and\n`conversationId` are ignored. A full storage allowance is refused with the same 413 and\n`QUOTA_STORAGE_EXCEEDED`, but the message only says that it is not available right now (not how much is\nstored: that is the partner's business) and `error.details.limit` is `storage`.\n\nAn account that administers a partner with a storage destination (`setPartnerStorageDestination`) has\nits files stored in the partner's own bucket instead. Such a file takes none of the allowance, its `url`\nis served from the partner's public address, and its `storage_key` is the key in the partner's bucket.\nThe file is never stored with Widgetic instead: when the destination cannot be used the upload is refused\nwith 503 and `STORAGE_DESTINATION_UNAVAILABLE`, and when the partner's storage rejects the file with\n502 and `STORAGE_DESTINATION_WRITE_FAILED`.\n\nPartner storage is not optional, and it does not depend on how the file arrives. A partner's own uploads (with\nits API key, an SDK token, or from the Widgetic website, the resumable route and the media library alike)\nand the uploads of its customers' editor sessions are kept in the partner's own storage or not at all, so a\npartner with no destination (or one that removed it after the session was made) has them refused with 409\nand `PARTNER_STORAGE_REQUIRED`; they are never stored with Widgetic. An editor session's browser is only\ntold that the feature is not available right now.\n",
5643
5643
  "security": [
5644
5644
  {
5645
5645
  "apiKeyAuth": []
@@ -5812,7 +5812,7 @@
5812
5812
  }
5813
5813
  },
5814
5814
  "get": {
5815
- "operationId": "uploadsGet",
5815
+ "operationId": "listUploads",
5816
5816
  "tags": [
5817
5817
  "Uploads"
5818
5818
  ],
@@ -5920,7 +5920,7 @@
5920
5920
  },
5921
5921
  "/uploads/limits": {
5922
5922
  "get": {
5923
- "operationId": "uploadsLimitsGet",
5923
+ "operationId": "getUploadLimits",
5924
5924
  "tags": [
5925
5925
  "Uploads"
5926
5926
  ],
@@ -5959,7 +5959,7 @@
5959
5959
  },
5960
5960
  "/uploads/{id}": {
5961
5961
  "get": {
5962
- "operationId": "uploadsIdGet",
5962
+ "operationId": "getUpload",
5963
5963
  "tags": [
5964
5964
  "Uploads"
5965
5965
  ],
@@ -6018,7 +6018,7 @@
6018
6018
  }
6019
6019
  },
6020
6020
  "delete": {
6021
- "operationId": "uploadsIdDelete",
6021
+ "operationId": "deleteUpload",
6022
6022
  "tags": [
6023
6023
  "Uploads"
6024
6024
  ],
@@ -6706,7 +6706,7 @@
6706
6706
  "put": {
6707
6707
  "operationId": "setPartnerStorageDestination",
6708
6708
  "summary": "Set where a partner's uploaded files are stored",
6709
- "description": "Points the partner at a bucket of its own on an S3-compatible service (Cloudflare R2, Amazon S3,\nWasabi, MinIO and the like). From then on, every file the account that administers the\npartner stores is kept in that bucket instead of with Widgetic, whichever way it arrives: a file sent with\n`uploadsPost` (with an API key, an SDK token, an editor session or from the Widgetic website), a resumable\nupload, the media library, and the files the agent tools and the MCP server save. It takes none of the\naccount's storage allowance, and its `url` is served from `publicBaseUrl`. The chunks of a resumable\nupload wait in Widgetic's temporary staging area until it is completed and are removed then: the finished\nfile is stored in your bucket and nowhere else.\n\nA destination is required. Partner storage is not optional: your customers' files, and your own however they\narrive, are kept in this destination and nowhere else. An editor session\n(`createManagedUserEditorSession`) of any surface cannot be made until a destination is set (409\n`PARTNER_STORAGE_REQUIRED`), a destination removed later stops the uploads of the sessions already made\n(the same 409), and your own upload with no destination (on any route, including a resumable upload, which\nis refused when it is started) is refused in the same way instead of being stored with Widgetic. A partner\ncannot be activated until it has a destination that works.\n\nThe destination is checked before it is saved. Widgetic writes a small test file under\n`<keyPrefix>widgetic-check/`, reads it back from `<publicBaseUrl>/<its key>`, and deletes it. If any\nstep fails nothing is saved and the answer is 422 `STORAGE_DESTINATION_UNVERIFIED`: `details.step` says\nwhere (`endpoint`, `write` or `public_read`), `details.reason` says why, and `param` names the field most\nlikely to be wrong.\n\nWhat the bucket needs:\n- an access key that may put objects into it (it may also delete objects, which lets the test file be\n cleaned up, but that is not required);\n- its files publicly readable at `publicBaseUrl`, either because the bucket is public or through a CDN.\n\nThe secret access key is stored encrypted and is never returned or logged; a response shows only the last\nfour characters of the access key id (`accessKeyHint`). Saving replaces the whole destination, so send\nevery field again, including the secret. Files already stored stay where they are, and keep working for\nas long as that bucket stays publicly readable.\n\nOnce a destination is set, an upload is never stored with Widgetic instead: when the destination cannot be\nused the upload is refused with 503 `STORAGE_DESTINATION_UNAVAILABLE`, and when the bucket rejects the\nfile with 502 `STORAGE_DESTINATION_WRITE_FAILED`.\n\nThe caller must be the person who administers the partner (an API key of that account works); anyone else\nis refused with 403 whether or not the partner exists. Widgetic administrators can set any partner's.\n",
6709
+ "description": "Points the partner at a bucket of its own on an S3-compatible service (Cloudflare R2, Amazon S3,\nWasabi, MinIO and the like). From then on, every file the account that administers the\npartner stores is kept in that bucket instead of with Widgetic, whichever way it arrives: a file sent with\n`uploadFile` (with an API key, an SDK token, an editor session or from the Widgetic website), a resumable\nupload, the media library, and the files the agent tools and the MCP server save. It takes none of the\naccount's storage allowance, and its `url` is served from `publicBaseUrl`. The chunks of a resumable\nupload wait in Widgetic's temporary staging area until it is completed and are removed then: the finished\nfile is stored in your bucket and nowhere else.\n\nA destination is required. Partner storage is not optional: your customers' files, and your own however they\narrive, are kept in this destination and nowhere else. An editor session\n(`createManagedUserEditorSession`) of any surface cannot be made until a destination is set (409\n`PARTNER_STORAGE_REQUIRED`), a destination removed later stops the uploads of the sessions already made\n(the same 409), and your own upload with no destination (on any route, including a resumable upload, which\nis refused when it is started) is refused in the same way instead of being stored with Widgetic. A partner\ncannot be activated until it has a destination that works.\n\nThe destination is checked before it is saved. Widgetic writes a small test file under\n`<keyPrefix>widgetic-check/`, reads it back from `<publicBaseUrl>/<its key>`, and deletes it. If any\nstep fails nothing is saved and the answer is 422 `STORAGE_DESTINATION_UNVERIFIED`: `details.step` says\nwhere (`endpoint`, `write` or `public_read`), `details.reason` says why, and `param` names the field most\nlikely to be wrong.\n\nWhat the bucket needs:\n- an access key that may put objects into it (it may also delete objects, which lets the test file be\n cleaned up, but that is not required);\n- its files publicly readable at `publicBaseUrl`, either because the bucket is public or through a CDN.\n\nThe secret access key is stored encrypted and is never returned or logged; a response shows only the last\nfour characters of the access key id (`accessKeyHint`). Saving replaces the whole destination, so send\nevery field again, including the secret. Files already stored stay where they are, and keep working for\nas long as that bucket stays publicly readable.\n\nOnce a destination is set, an upload is never stored with Widgetic instead: when the destination cannot be\nused the upload is refused with 503 `STORAGE_DESTINATION_UNAVAILABLE`, and when the bucket rejects the\nfile with 502 `STORAGE_DESTINATION_WRITE_FAILED`.\n\nThe caller must be the person who administers the partner (an API key of that account works); anyone else\nis refused with 403 whether or not the partner exists. Widgetic administrators can set any partner's.\n",
6710
6710
  "tags": [
6711
6711
  "Partners"
6712
6712
  ],
@@ -7570,7 +7570,7 @@
7570
7570
  "get": {
7571
7571
  "operationId": "getPartnerStorageUsage",
7572
7572
  "summary": "What a partner's customers store",
7573
- "description": "Says how many files, and how many bytes, your account keeps, in total and for each of your managed users, and\nhow much of it is in Widgetic's storage and how much in your own storage destination\n(`setPartnerStorageDestination`). Use it to see which customers store the most, or to charge them for it.\n\nA file is counted for a managed user when it was filed under that user: by naming `managed_user_id` or\n`managed_user_external_id` when you upload it (`uploadsPost`, or the metadata of a resumable upload), or\nbecause it was uploaded through that user's editor session, which files everything under its user. The files\nthat are not filed under anyone (your own, and the ones uploaded without naming a managed user) are the row\nwhose `managedUserId` is null. Deleted files are not counted. To list the files of one managed user, use the\n`managed_user_id` filter of `uploadsGet`.\n\nThe answer is counted when you ask, so it is always current. The groups are ordered by size, the heaviest\nfirst, and `page.hasMore` says whether more follow.\n\nThe caller must be the person who administers the partner (an API key of that account works, with the\n`partner:read` scope), or a Widgetic administrator.\n",
7573
+ "description": "Says how many files, and how many bytes, your account keeps, in total and for each of your managed users, and\nhow much of it is in Widgetic's storage and how much in your own storage destination\n(`setPartnerStorageDestination`). Use it to see which customers store the most, or to charge them for it.\n\nA file is counted for a managed user when it was filed under that user: by naming `managed_user_id` or\n`managed_user_external_id` when you upload it (`uploadFile`, or the metadata of a resumable upload), or\nbecause it was uploaded through that user's editor session, which files everything under its user. The files\nthat are not filed under anyone (your own, and the ones uploaded without naming a managed user) are the row\nwhose `managedUserId` is null. Deleted files are not counted. To list the files of one managed user, use the\n`managed_user_id` filter of `listUploads`.\n\nThe answer is counted when you ask, so it is always current. The groups are ordered by size, the heaviest\nfirst, and `page.hasMore` says whether more follow.\n\nThe caller must be the person who administers the partner (an API key of that account works, with the\n`partner:read` scope), or a Widgetic administrator.\n",
7574
7574
  "tags": [
7575
7575
  "Partners"
7576
7576
  ],
@@ -9819,7 +9819,7 @@
9819
9819
  },
9820
9820
  "/operations/{id}": {
9821
9821
  "get": {
9822
- "operationId": "operationsIdGet",
9822
+ "operationId": "getOperation",
9823
9823
  "summary": "Get operation status",
9824
9824
  "description": "Follows work that carries on after the response that started it. Duplicating a composition,\nfor one, answers 202 with an `operationId`: ask for that operation until its `status` is\n`completed` (or `failed`, with the reason in `error`). A finished duplication names the new\ncomposition in `metadata.newCompositionId`.\n\nAn operation belongs to the user who started it. Asking for somebody else's operation answers\n404, exactly as for one that does not exist. Administrators may read any operation.\n",
9825
9825
  "tags": [
@@ -9850,7 +9850,7 @@
9850
9850
  "content": {
9851
9851
  "application/json": {
9852
9852
  "schema": {
9853
- "$ref": "#/components/schemas/OperationsIdGetResponse"
9853
+ "$ref": "#/components/schemas/GetOperationResponse"
9854
9854
  }
9855
9855
  }
9856
9856
  }
@@ -10434,7 +10434,7 @@
10434
10434
  "post": {
10435
10435
  "operationId": "createManagedUserEditorSession",
10436
10436
  "summary": "Create an editor session for a managed user",
10437
- "description": "Makes a short-lived credential that lets the browser of ONE of your managed users use Widgetic's editor\npieces, such as the File Browser and the composition editor, without your API key ever reaching that\nbrowser. Call this from your server when the page that hosts the editor opens, and hand the `token` in\nthe answer to that page.\n\nThe token is shown once. It starts with `wgt_ses_` and the browser sends it as\n`Authorization: Bearer <token>`. It can do only what the `surfaces` you name allow, and only for this\nmanaged user:\n\n- `files`: upload a file (`uploadsPost`) and list the files uploaded for this user (`uploadsGet`). Every\n file is filed for this user and stored in your own storage destination, never in Widgetic's: a file a\n customer uploads is yours to keep, and takes none of your storage allowance. Partner storage is not\n optional, so no session, whatever its surfaces, can be made until you have set a destination\n (`setPartnerStorageDestination`); until then it is refused with 409 and `PARTNER_STORAGE_REQUIRED`, and\n when the destination cannot be used with 503 and `STORAGE_DESTINATION_UNAVAILABLE`. A destination you\n remove after the session was made stops its uploads too (the same 409; the browser is only told that\n the feature is not available right now). To keep a customer from uploading, leave `files` out of the\n session and hand the editors your own media library instead (`mediaLibrary`).\n- `editor`: edit one of this user's compositions: read it (`getCompositionById`, its content, design,\n embed settings and schemas), check a content change (`validateCompositionContent`), and change its\n name, content, design and embed settings (`updateComposition`, `setDynamicContent`). For a widget that\n answers visitors' questions from documents (the `ai-answers` adapter), it also lists those documents,\n adds one as text or as a file (a text file or a picture; a PDF once PDFs are read), and removes one\n (`getAiAnswersKnowledge`, `addAiAnswersKnowledgeDocument`, `addAiAnswersKnowledgeFile`,\n `removeAiAnswersKnowledgeDocument`); adding costs no credits, and is limited for each of your users\n separately. It can reach\n only compositions you created for this managed user (tag them with `managedUserId` when you create\n them); any other composition, including another of your users', answers 404.\n- `creator`: use Widgetic's widget creator for this user, including its AI. Draw on canvases and save\n them (`getAllCanvases`, `getCanvas`, `createCanvas`, `updateCanvas`, `previewDeleteCanvas`,\n `deleteCanvas`); make, change, copy and delete the widgets on them (`createWidget`, `getWidgets`,\n `getWidgetsBatch`, `updateWidget`, `uploadWidgetThumbnail`, `duplicateWidget`, `deleteWidget`);\n list and make the compositions of a widget it built (`getAllCompositions`, `createComposition`), which\n is how it shows the widget with sample values; keep the\n conversation of each widget (`getConversationsByWidgetId`, `createConversationForWidget`,\n `updateConversation`, `getMessages`, `createMessage`, `updateMessage`, `restoreCheckpoint`); and read a\n widget's schemas and give it its repository (`getWidgetContentSchema`, `getWidgetDesignSchema`,\n `updateWidgetRepository`). The AI that builds a widget is part of it: list the models\n (`agentModelsGet`), open the widget's repository (`agentRepositoriesPost`,\n `agentRepositoriesRepoIdGet`), start a generation and follow or cancel it (`agentCodeGeneratePost`,\n `operationsStreamGet`, `operationsIdGet`, `operationsIdCancelPost`), build and preview the result\n (`agentWidgetBuilderRepoHeadWidgetIdGet`, `buildWidgetFromRepo`, `previewWidgetVersion`), publish a\n version of the widget and move between its versions (`agentWidgetBuilderPublishWidgetIdPost`,\n `getWidgetPublishHistory`, `setWidgetPublishHistoryLive`, `renameWidgetPublishHistoryTitle`), and\n turn a stroke or a sentence into a decision (`agentShapeRecognizePost`, `agentDesignResolvePost`). It can\n also offer the customer your presets as starting points: read them and ask for a copy for this customer\n (`listMyPresets`, `copyMyPreset`; you choose the presets with `setPartnerPreset`).\n What the session makes is filed for this managed user, and the lists it reads hold only this user's\n canvases, widgets and compositions. It can reach only canvases, widgets, compositions, repositories,\n uploaded files and operations made for this managed user (tag the canvases and widgets you create\n with `managedUserId`); any other canvas, widget, composition, conversation, message, repository, file\n or operation, including another of your users', answers 404. The creator also saves the composition\n it is editing (`updateComposition`, from the `editor` surface) and attaches pictures to its chat\n (`uploadsPost`, from the `files` surface), and the surfaces do not imply one another: to open the\n whole creator for a user, ask for `creator`, `editor` and `files` together. A generation or a build\n one user starts can be followed and cancelled by that user and by you, never by another of your\n users. The AI is paid for by your account, as your own calls are: its credits and allowances are\n yours. A session cannot make a widget public (publishing a version does not), file one under a\n project or an organization, or set anything the creator does not set: a body with another field is\n refused with 403 and `EDITOR_SESSION_FIELD_NOT_ALLOWED`.\n- `workflows`: use Widgetic's Workflows editor for this user. List their workflows and the compositions\n a workflow of theirs can chain (`listWorkspaceWorkflows`, `listWorkspaceWorkflowCompositionOptions`);\n list the starting points you offer them and make a workflow from one, which gives the user their own copy\n of every widget it chains, a composition of their own on each copy, and a draft\n (`listWorkspaceWorkflowPresets`, `createWorkspaceWorkflowFromPreset`; you offer them with\n `setPartnerWorkflowPreset`);\n make, open, change and delete one (`createWorkspaceWorkflow`, `getWorkspaceWorkflow`,\n `saveWorkspaceWorkflow`, `deleteWorkspaceWorkflow`) and copy it (`duplicateWorkspaceWorkflow`); publish\n it or discard the changes of its draft (`publishWorkspaceWorkflow`,\n `discardWorkspaceWorkflowChanges`); read and restore its versions (`listWorkspaceWorkflowVersions`,\n `getWorkspaceWorkflowVersion`, `restoreWorkspaceWorkflowVersion`); pause, resume, archive and unarchive it\n (`pauseWorkspaceWorkflow`, `resumeWorkspaceWorkflow`, `archiveWorkspaceWorkflow`,\n `unarchiveWorkspaceWorkflow`); and read its counts (`getWorkspaceWorkflowStats`). The workspace in each\n path is `personal`: a session has no other, and a path that names an organization is refused. What the\n session makes is filed for this managed user (`managedUserId`), the lists hold only this user's workflows,\n and it can reach only workflows made for this managed user; any other workflow, including one of yours\n or of another of your users, answers 404. A workflow can chain only the compositions you made for this\n managed user (tag them with `managedUserId`): one that belongs to anybody else is not available, and\n publishing a workflow that uses it is refused. A customer can have at most 50 workflows, and what a\n customer's session reads never says who published a version. A session cannot set who a workflow belongs\n to or which workspace it is in: a body with another field is refused with 403 and\n `EDITOR_SESSION_FIELD_NOT_ALLOWED`.\n\nEverything else is refused with 403 and `EDITOR_SESSION_ROUTE_NOT_ALLOWED`: a session cannot read your\naccount, make more sessions, change your presets or delete a composition, and a session without the `creator` surface cannot\ncreate or list compositions. Create the composition yourself with your API key, then open the editor on it.\n\nA session ends at `expiresAt` (at most four hours), when you end it (`revokeManagedUserEditorSession`),\nor when the managed user is switched off or deleted. A managed user can have at most 100 live sessions at\nonce (`429 EDITOR_SESSION_LIMIT_REACHED`). A session that is bound to a web page (`allowedOrigin`) is\nrefused from any other origin.\n\nThe AI the session runs is paid for with your credits. Set `maxCredits` to hold the session to a number\nof them: once its generations have taken that many (a generation that fails is refunded and does not\ncount), the next one is refused with 402 and `EDITOR_SESSION_CREDIT_LIMIT_REACHED`, and the browser is told\nonly that the feature is not available right now. Without it, the limit Widgetic has set for your account\napplies when it has set one (the same limit for every session you make, and `maxCredits: null` asks for\nnone), and otherwise the credits of your account are the only ceiling. What each of your users' sessions\nhas spent is in `getManagedUserUsage`.\n\nEach call makes a new session. It does not take an `Idempotency-Key`: the answer holds the token, and\nthe token is never stored where a retry could read it back. The answer is sent with\n`Cache-Control: no-store`.\n",
10437
+ "description": "Makes a short-lived credential that lets the browser of ONE of your managed users use Widgetic's editor\npieces, such as the File Browser and the composition editor, without your API key ever reaching that\nbrowser. Call this from your server when the page that hosts the editor opens, and hand the `token` in\nthe answer to that page.\n\nThe token is shown once. It starts with `wgt_ses_` and the browser sends it as\n`Authorization: Bearer <token>`. It can do only what the `surfaces` you name allow, and only for this\nmanaged user:\n\n- `files`: upload a file (`uploadFile`) and list the files uploaded for this user (`listUploads`). Every\n file is filed for this user and stored in your own storage destination, never in Widgetic's: a file a\n customer uploads is yours to keep, and takes none of your storage allowance. Partner storage is not\n optional, so no session, whatever its surfaces, can be made until you have set a destination\n (`setPartnerStorageDestination`); until then it is refused with 409 and `PARTNER_STORAGE_REQUIRED`, and\n when the destination cannot be used with 503 and `STORAGE_DESTINATION_UNAVAILABLE`. A destination you\n remove after the session was made stops its uploads too (the same 409; the browser is only told that\n the feature is not available right now). To keep a customer from uploading, leave `files` out of the\n session and hand the editors your own media library instead (`mediaLibrary`).\n- `editor`: edit one of this user's compositions: read it (`getCompositionById`, its content, design,\n embed settings and schemas), check a content change (`validateCompositionContent`), and change its\n name, content, design and embed settings (`updateComposition`, `setDynamicContent`). For a widget that\n answers visitors' questions from documents (the `ai-answers` adapter), it also lists those documents,\n adds one as text or as a file (a text file or a picture; a PDF once PDFs are read), and removes one\n (`getAiAnswersKnowledge`, `addAiAnswersKnowledgeDocument`, `addAiAnswersKnowledgeFile`,\n `removeAiAnswersKnowledgeDocument`); adding costs no credits, and is limited for each of your users\n separately. It can reach\n only compositions you created for this managed user (tag them with `managedUserId` when you create\n them); any other composition, including another of your users', answers 404.\n- `creator`: use Widgetic's widget creator for this user, including its AI. Draw on canvases and save\n them (`getAllCanvases`, `getCanvas`, `createCanvas`, `updateCanvas`, `previewDeleteCanvas`,\n `deleteCanvas`); make, change, copy and delete the widgets on them (`createWidget`, `getWidgets`,\n `getWidgetsBatch`, `updateWidget`, `uploadWidgetThumbnail`, `duplicateWidget`, `deleteWidget`);\n list and make the compositions of a widget it built (`getAllCompositions`, `createComposition`), which\n is how it shows the widget with sample values; keep the\n conversation of each widget (`getConversationsByWidgetId`, `createConversationForWidget`,\n `updateConversation`, `getMessages`, `createMessage`, `updateMessage`, `restoreCheckpoint`); and read a\n widget's schemas and give it its repository (`getWidgetContentSchema`, `getWidgetDesignSchema`,\n `updateWidgetRepository`). The AI that builds a widget is part of it: list the models\n (`listLlmModels`), open the widget's repository (`createRepository`,\n `getRepository`), start a generation and follow or cancel it (`generateCode`,\n `streamOperationUpdates`, `getOperation`, `cancelOperation`), build and preview the result\n (`getWidgetRepositoryHead`, `buildWidgetFromRepo`, `previewWidgetVersion`), publish a\n version of the widget and move between its versions (`publishBuiltWidget`,\n `getWidgetPublishHistory`, `setWidgetPublishHistoryLive`, `renameWidgetPublishHistoryTitle`), and\n turn a stroke or a sentence into a decision (`recognizeShape`, `resolveDesignProperty`). It can\n also offer the customer your presets as starting points: read them and ask for a copy for this customer\n (`listMyPresets`, `copyMyPreset`; you choose the presets with `setPartnerPreset`).\n What the session makes is filed for this managed user, and the lists it reads hold only this user's\n canvases, widgets and compositions. It can reach only canvases, widgets, compositions, repositories,\n uploaded files and operations made for this managed user (tag the canvases and widgets you create\n with `managedUserId`); any other canvas, widget, composition, conversation, message, repository, file\n or operation, including another of your users', answers 404. The creator also saves the composition\n it is editing (`updateComposition`, from the `editor` surface) and attaches pictures to its chat\n (`uploadFile`, from the `files` surface), and the surfaces do not imply one another: to open the\n whole creator for a user, ask for `creator`, `editor` and `files` together. A generation or a build\n one user starts can be followed and cancelled by that user and by you, never by another of your\n users. The AI is paid for by your account, as your own calls are: its credits and allowances are\n yours. A session cannot make a widget public (publishing a version does not), file one under a\n project or an organization, or set anything the creator does not set: a body with another field is\n refused with 403 and `EDITOR_SESSION_FIELD_NOT_ALLOWED`.\n- `workflows`: use Widgetic's Workflows editor for this user. List their workflows and the compositions\n a workflow of theirs can chain (`listWorkspaceWorkflows`, `listWorkspaceWorkflowCompositionOptions`);\n list the starting points you offer them and make a workflow from one, which gives the user their own copy\n of every widget it chains, a composition of their own on each copy, and a draft\n (`listWorkspaceWorkflowPresets`, `createWorkspaceWorkflowFromPreset`; you offer them with\n `setPartnerWorkflowPreset`);\n make, open, change and delete one (`createWorkspaceWorkflow`, `getWorkspaceWorkflow`,\n `saveWorkspaceWorkflow`, `deleteWorkspaceWorkflow`) and copy it (`duplicateWorkspaceWorkflow`); publish\n it or discard the changes of its draft (`publishWorkspaceWorkflow`,\n `discardWorkspaceWorkflowChanges`); read and restore its versions (`listWorkspaceWorkflowVersions`,\n `getWorkspaceWorkflowVersion`, `restoreWorkspaceWorkflowVersion`); pause, resume, archive and unarchive it\n (`pauseWorkspaceWorkflow`, `resumeWorkspaceWorkflow`, `archiveWorkspaceWorkflow`,\n `unarchiveWorkspaceWorkflow`); and read its counts (`getWorkspaceWorkflowStats`). The workspace in each\n path is `personal`: a session has no other, and a path that names an organization is refused. What the\n session makes is filed for this managed user (`managedUserId`), the lists hold only this user's workflows,\n and it can reach only workflows made for this managed user; any other workflow, including one of yours\n or of another of your users, answers 404. A workflow can chain only the compositions you made for this\n managed user (tag them with `managedUserId`): one that belongs to anybody else is not available, and\n publishing a workflow that uses it is refused. A customer can have at most 50 workflows, and what a\n customer's session reads never says who published a version. A session cannot set who a workflow belongs\n to or which workspace it is in: a body with another field is refused with 403 and\n `EDITOR_SESSION_FIELD_NOT_ALLOWED`.\n\nEverything else is refused with 403 and `EDITOR_SESSION_ROUTE_NOT_ALLOWED`: a session cannot read your\naccount, make more sessions, change your presets or delete a composition, and a session without the `creator` surface cannot\ncreate or list compositions. Create the composition yourself with your API key, then open the editor on it.\n\nA session ends at `expiresAt` (at most four hours), when you end it (`revokeManagedUserEditorSession`),\nor when the managed user is switched off or deleted. A managed user can have at most 100 live sessions at\nonce (`429 EDITOR_SESSION_LIMIT_REACHED`). A session that is bound to a web page (`allowedOrigin`) is\nrefused from any other origin.\n\nThe AI the session runs is paid for with your credits. Set `maxCredits` to hold the session to a number\nof them: once its generations have taken that many (a generation that fails is refunded and does not\ncount), the next one is refused with 402 and `EDITOR_SESSION_CREDIT_LIMIT_REACHED`, and the browser is told\nonly that the feature is not available right now. Without it, the limit Widgetic has set for your account\napplies when it has set one (the same limit for every session you make, and `maxCredits: null` asks for\nnone), and otherwise the credits of your account are the only ceiling. What each of your users' sessions\nhas spent is in `getManagedUserUsage`.\n\nEach call makes a new session. It does not take an `Idempotency-Key`: the answer holds the token, and\nthe token is never stored where a retry could read it back. The answer is sent with\n`Cache-Control: no-store`.\n",
10438
10438
  "tags": [
10439
10439
  "Managed Users"
10440
10440
  ],
@@ -12724,7 +12724,7 @@
12724
12724
  {
12725
12725
  "lang": "TypeScript",
12726
12726
  "label": "TypeScript SDK",
12727
- "source": "import { randomUUID } from 'node:crypto';\nimport { Configuration, CompositionsApi, OperationsApi } from '@widgetic/api-sdk-ts';\n\nconst config = new Configuration({\n apiKey: 'YOUR_API_KEY'\n});\n\nconst compositionsApi = new CompositionsApi(config);\nconst operationsApi = new OperationsApi(config);\n\ntry {\n const started = await compositionsApi.duplicateComposition(\n {\n id: 'composition_123',\n duplicateCompositionRequest: {\n name: 'My Duplicated Composition',\n includeDatabase: false\n }\n },\n // The call needs an Idempotency-Key header and the SDK does not add one: keep the headers\n // it already set and add the key. Reuse the same key if you retry this call.\n async ({ init }) => ({ headers: { ...init.headers, 'Idempotency-Key': randomUUID() } })\n );\n \n // The duplicate is made after the answer: ask for the operation until it has finished\n const operationId = started.data?.operationId;\n if (!operationId) throw new Error('The answer has no operationId');\n \n const finalStatuses = ['completed', 'failed', 'cancelled'];\n let operation = await operationsApi.operationsIdGet({ id: operationId });\n while (!finalStatuses.includes(operation.status ?? '')) {\n await new Promise((resolve) => setTimeout(resolve, 1000));\n operation = await operationsApi.operationsIdGet({ id: operationId });\n }\n \n if (operation.status !== 'completed') {\n console.error('Duplication did not finish:', operation.status, operation.error);\n } else {\n console.log('Duplicated composition:', operation.metadata?.newCompositionId);\n if (operation.metadata?.warnings?.length) {\n console.warn('Warnings:', operation.metadata.warnings);\n }\n }\n} catch (error) {\n if (error.response?.status === 404) {\n console.error('Source composition not found');\n } else {\n console.error('Failed to duplicate composition:', error);\n }\n}\n"
12727
+ "source": "import { randomUUID } from 'node:crypto';\nimport { Configuration, CompositionsApi, OperationsApi } from '@widgetic/api-sdk-ts';\n\nconst config = new Configuration({\n apiKey: 'YOUR_API_KEY'\n});\n\nconst compositionsApi = new CompositionsApi(config);\nconst operationsApi = new OperationsApi(config);\n\ntry {\n const started = await compositionsApi.duplicateComposition(\n {\n id: 'composition_123',\n duplicateCompositionRequest: {\n name: 'My Duplicated Composition',\n includeDatabase: false\n }\n },\n // The call needs an Idempotency-Key header and the SDK does not add one: keep the headers\n // it already set and add the key. Reuse the same key if you retry this call.\n async ({ init }) => ({ headers: { ...init.headers, 'Idempotency-Key': randomUUID() } })\n );\n \n // The duplicate is made after the answer: ask for the operation until it has finished\n const operationId = started.data?.operationId;\n if (!operationId) throw new Error('The answer has no operationId');\n \n const finalStatuses = ['completed', 'failed', 'cancelled'];\n let operation = await operationsApi.getOperation({ id: operationId });\n while (!finalStatuses.includes(operation.status ?? '')) {\n await new Promise((resolve) => setTimeout(resolve, 1000));\n operation = await operationsApi.getOperation({ id: operationId });\n }\n \n if (operation.status !== 'completed') {\n console.error('Duplication did not finish:', operation.status, operation.error);\n } else {\n console.log('Duplicated composition:', operation.metadata?.newCompositionId);\n if (operation.metadata?.warnings?.length) {\n console.warn('Warnings:', operation.metadata.warnings);\n }\n }\n} catch (error) {\n if (error.response?.status === 404) {\n console.error('Source composition not found');\n } else {\n console.error('Failed to duplicate composition:', error);\n }\n}\n"
12728
12728
  }
12729
12729
  ]
12730
12730
  }
@@ -19151,6 +19151,16 @@
19151
19151
  "minimum": 1,
19152
19152
  "maximum": 50,
19153
19153
  "description": "How many times (1 when not given)."
19154
+ },
19155
+ "r": {
19156
+ "type": "string",
19157
+ "enum": [
19158
+ "t",
19159
+ "e",
19160
+ "b",
19161
+ "o"
19162
+ ],
19163
+ "description": "Only on an `f` event: why moving the visitor on failed. `t` the composition did not appear in time,\n`e` the widget in it reported an error, `b` the composition could not be built, `o` another reason (a\nstep was already on its way, or the page was going away). Left out by an embed that does not say why;\na letter this server does not know is read as left out, and the failure is still counted. On an `n` or\nan `e` event it is ignored. Never a message: one letter, so that nothing a visitor typed can ride on it.\n"
19154
19164
  }
19155
19165
  }
19156
19166
  }
@@ -20301,10 +20311,17 @@
20301
20311
  },
20302
20312
  "failed": {
20303
20313
  "type": "array",
20304
- "description": "Times moving on to a block failed (it did not load in time) and the visitor stayed.",
20314
+ "description": "Times moving on to a block failed and the visitor stayed, whatever the reason: every failure is counted here,\nincluding the ones whose browser did not say why. A try is counted, not a visitor: a step is tried once more\nafter 30 seconds, so one visitor can count twice.\n",
20305
20315
  "items": {
20306
20316
  "$ref": "#/components/schemas/WorkflowCounter"
20307
20317
  }
20318
+ },
20319
+ "failedReasons": {
20320
+ "type": "array",
20321
+ "description": "Why those failed, where the visitor's browser said why: one entry for each block and reason that has a count. The\nreasons of a block add up to at most its `failed` total, never more: a failure reported by an embed that does not\nsay why (an older one) is in `failed` and in none of these, so a block whose reasons add up to less has some of\nunknown reason. Empty when no failure in the range had a reason. Sent by gateways that keep reasons; a client\nthat reads a gateway without them treats a missing list as empty.\n",
20322
+ "items": {
20323
+ "$ref": "#/components/schemas/WorkflowFailureReasonCounter"
20324
+ }
20308
20325
  }
20309
20326
  },
20310
20327
  "example": {
@@ -20321,9 +20338,48 @@
20321
20338
  ],
20322
20339
  "failed": [
20323
20340
  "Example WorkflowCounter"
20341
+ ],
20342
+ "failedReasons": [
20343
+ "Example WorkflowFailureReasonCounter"
20324
20344
  ]
20325
20345
  }
20326
20346
  },
20347
+ "WorkflowFailureReason": {
20348
+ "type": "string",
20349
+ "enum": [
20350
+ "timeout",
20351
+ "widget_error",
20352
+ "build",
20353
+ "other"
20354
+ ],
20355
+ "description": "Why a composition could not be shown to a visitor. `timeout`: it did not appear in time (the embed waits eight\nseconds). `widget_error`: the widget in it reported an error. `build`: the embed could not build it at all. `other`:\nanother step was already on its way, or the page was going away. A closed list: never a message and never a code a\nwidget chose.\n"
20356
+ },
20357
+ "WorkflowFailureReasonCounter": {
20358
+ "type": "object",
20359
+ "required": [
20360
+ "id",
20361
+ "reason",
20362
+ "total"
20363
+ ],
20364
+ "properties": {
20365
+ "id": {
20366
+ "type": "string",
20367
+ "description": "The block (a composition) that could not be shown."
20368
+ },
20369
+ "reason": {
20370
+ "$ref": "#/components/schemas/WorkflowFailureReason"
20371
+ },
20372
+ "total": {
20373
+ "type": "integer",
20374
+ "description": "How many tries failed for this reason."
20375
+ }
20376
+ },
20377
+ "example": {
20378
+ "id": "Example id",
20379
+ "reason": null,
20380
+ "total": 42
20381
+ }
20382
+ },
20327
20383
  "WorkflowCompositionField": {
20328
20384
  "type": "object",
20329
20385
  "required": [
@@ -21284,7 +21340,7 @@
21284
21340
  "type": "string",
21285
21341
  "format": "uuid",
21286
21342
  "nullable": true,
21287
- "description": "The managed user the file was uploaded for, or null when it is the account's own. List one managed user's files with the `managed_user_id` or `managed_user_external_id` query parameter of `uploadsGet`."
21343
+ "description": "The managed user the file was uploaded for, or null when it is the account's own. List one managed user's files with the `managed_user_id` or `managed_user_external_id` query parameter of `listUploads`."
21288
21344
  },
21289
21345
  "purpose": {
21290
21346
  "type": "string",
@@ -21320,18 +21376,18 @@
21320
21376
  "properties": {
21321
21377
  "multipart_max_bytes": {
21322
21378
  "type": "integer",
21323
- "description": "The largest file `uploadsPost` takes in one request, in bytes. The same for every account."
21379
+ "description": "The largest file `uploadFile` takes in one request, in bytes. The same for every account."
21324
21380
  },
21325
21381
  "multipart_mime_types": {
21326
21382
  "type": "array",
21327
21383
  "items": {
21328
21384
  "type": "string"
21329
21385
  },
21330
- "description": "The file types `uploadsPost` takes for media (`content-property` uploads)"
21386
+ "description": "The file types `uploadFile` takes for media (`content-property` uploads)"
21331
21387
  },
21332
21388
  "tus_enabled": {
21333
21389
  "type": "boolean",
21334
- "description": "Whether resumable uploads are switched on. They need a signed-in session; an API key uses `uploadsPost`."
21390
+ "description": "Whether resumable uploads are switched on. They need a signed-in session; an API key uses `uploadFile`."
21335
21391
  },
21336
21392
  "tus_max_bytes": {
21337
21393
  "type": "integer",
@@ -27596,7 +27652,7 @@
27596
27652
  }
27597
27653
  }
27598
27654
  },
27599
- "OperationsIdGetResponse": {
27655
+ "GetOperationResponse": {
27600
27656
  "type": "object",
27601
27657
  "required": [
27602
27658
  "success",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@widgetic/api-contracts",
3
- "version": "1.11.115",
3
+ "version": "1.11.127",
4
4
  "description": "What the Widgetic API and the Widgetic MCP server accept, as data: the public OpenAPI description and the MCP tool contract. Written by the Widgetic API gateway; the Widgetic CLI is generated from it.",
5
5
  "author": "Widgetic",
6
6
  "license": "SEE LICENSE IN LICENSE",