path: root/comm/mail/components/extensions/schemas/cloudFile.json

[
  {
    "namespace": "manifest",
    "types": [
      {
        "$extend": "WebExtensionManifest",
        "properties": {
          "cloud_file": {
            "type": "object",
            "additionalProperties": {
              "$ref": "UnrecognizedProperty"
            },
            "properties": {
              "browser_style": {
                "type": "boolean",
                "description": "Enable browser styles in the ``management_url`` page. See the `MDN documentation on browser styles <|link-mdn-browser-styles|>`__ for more information.",
                "optional": true,
                "default": false
              },
              "data_format": {
                "type": "string",
                "optional": true,
                "deprecated": true,
                "description": "This property is no longer used. The only supported data format for the ``data`` argument in :ref:`cloudFile.onFileUpload` is |File|."
              },
              "reuse_uploads": {
                "description": "If a previously uploaded cloud file attachment is reused at a later time in a different message, Thunderbird may use the already known ``url`` and ``templateInfo`` values without triggering the registered :ref:`cloudFile.onFileUpload` listener again. Setting this option to <value>false</value> will always trigger the registered listener, providing the already known values through the ``relatedFileInfo`` parameter of the :ref:`cloudFile.onFileUpload` event, to let the provider decide how to handle these cases.",
                "type": "boolean",
                "optional": true,
                "default": true
              },
              "management_url": {
                "type": "string",
                "format": "relativeUrl",
                "preprocess": "localize",
                "description": "A page for configuring accounts, to be displayed in the preferences UI. **Note:** Within this UI only a limited subset of the WebExtension APIs is available: ``cloudFile``, ``extension``, ``i18n``, ``runtime``, ``storage``, ``test``."
              },
              "name": {
                "type": "string",
                "preprocess": "localize",
                "description": "Name of the cloud file service."
              },
              "new_account_url": {
                "type": "string",
                "optional": true,
                "deprecated": true,
                "description": "This property was never used."
              },
              "service_url": {
                "type": "string",
                "optional": true,
                "deprecated": true,
                "description": "This property is no longer used. The ``service_url`` property of the :ref:`cloudFile.CloudFileTemplateInfo` object returned by the :ref:`cloudFile.onFileUpload` event can be used to add a <em>Learn more about</em> link to the footer of the cloud file attachment element."
              }
            },
            "optional": true
          }
        }
      }
    ]
  },
  {
    "namespace": "cloudFile",
    "permissions": ["manifest:cloud_file"],
    "allowedContexts": ["content"],
    "events": [
      {
        "name": "onFileUpload",
        "type": "function",
        "description": "Fired when a file should be uploaded to the cloud file provider.",
        "parameters": [
          {
            "name": "account",
            "$ref": "CloudFileAccount",
            "description": "The account used for the file upload."
          },
          {
            "name": "fileInfo",
            "$ref": "CloudFile",
            "description": "The file to upload."
          },
          {
            "name": "tab",
            "$ref": "tabs.Tab",
            "description": "The tab where the upload was initiated. Currently only available for the message composer."
          },
          {
            "$ref": "RelatedCloudFile",
            "name": "relatedFileInfo",
            "optional": true,
            "description": "Information about an already uploaded file, which is related to this upload."
          }
        ],
        "returns": {
          "type": "object",
          "properties": {
            "aborted": {
              "type": "boolean",
              "description": "Set this to <value>true</value> if the file upload was aborted by the user and an :ref:`cloudFile.onFileUploadAbort` event has been received. No error message will be shown to the user.",
              "optional": true
            },
            "error": {
              "choices": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string"
                }
              ],
              "description": "Report an error to the user. Set this to <value>true</value> for showing a generic error message, or set a specific error message.",
              "optional": true
            },
            "url": {
              "type": "string",
              "description": "The URL where the uploaded file can be accessed.",
              "optional": true
            },
            "templateInfo": {
              "$ref": "CloudFileTemplateInfo",
              "description": "Additional file information used in the cloud file entry added to the message.",
              "optional": true
            }
          }
        }
      },
      {
        "name": "onFileUploadAbort",
        "type": "function",
        "parameters": [
          {
            "name": "account",
            "$ref": "CloudFileAccount",
            "description": "The account used for the file upload."
          },
          {
            "type": "integer",
            "name": "fileId",
            "minimum": 1,
            "description": "An identifier for this file."
          },
          {
            "name": "tab",
            "$ref": "tabs.Tab",
            "description": "The tab where the upload was initiated. Currently only available for the message composer."
          }
        ]
      },
      {
        "name": "onFileRename",
        "type": "function",
        "description": "Fired when a previously uploaded file should be renamed.",
        "parameters": [
          {
            "name": "account",
            "$ref": "CloudFileAccount",
            "description": "The account used for the file upload."
          },
          {
            "type": "integer",
            "name": "fileId",
            "minimum": 1,
            "description": "An identifier for the file which should be renamed."
          },
          {
            "type": "string",
            "name": "newName",
            "description": "The new name of the file."
          },
          {
            "name": "tab",
            "$ref": "tabs.Tab",
            "description": "The tab where the rename was initiated. Currently only available for the message composer."
          }
        ],
        "returns": {
          "type": "object",
          "properties": {
            "error": {
              "choices": [
                {
                  "type": "boolean"
                },
                {
                  "type": "string"
                }
              ],
              "description": "Report an error to the user. Set this to <value>true</value> for showing a generic error message, or set a specific error message.",
              "optional": true
            },
            "url": {
              "type": "string",
              "description": "The URL where the renamed file can be accessed.",
              "optional": true
            }
          }
        }
      },
      {
        "name": "onFileDeleted",
        "type": "function",
        "description": "Fired when a previously uploaded file should be deleted.",
        "parameters": [
          {
            "name": "account",
            "$ref": "CloudFileAccount",
            "description": "The account used for the file upload."
          },
          {
            "type": "integer",
            "name": "fileId",
            "minimum": 1,
            "description": "An identifier for this file."
          },
          {
            "name": "tab",
            "$ref": "tabs.Tab",
            "description": "The tab where the upload was initiated. Currently only available for the message composer."
          }
        ]
      },
      {
        "name": "onAccountAdded",
        "type": "function",
        "description": "Fired when a cloud file account of this add-on was created.",
        "parameters": [
          {
            "name": "account",
            "$ref": "CloudFileAccount",
            "description": "The created account."
          }
        ]
      },
      {
        "name": "onAccountDeleted",
        "type": "function",
        "description": "Fired when a cloud file account of this add-on was deleted.",
        "parameters": [
          {
            "name": "accountId",
            "type": "string",
            "description": "The id of the removed account."
          }
        ]
      }
    ],
    "types": [
      {
        "id": "CloudFileAccount",
        "type": "object",
        "description": "Information about a cloud file account.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the account."
          },
          "configured": {
            "type": "boolean",
            "description": "If true, the account is configured and ready to use. Only configured accounts are offered to the user."
          },
          "name": {
            "type": "string",
            "description": "A user-friendly name for this account."
          },
          "uploadSizeLimit": {
            "type": "integer",
            "minimum": -1,
            "optional": true,
            "description": "The maximum size in bytes for a single file to upload. Set to <value>-1</value> if unlimited."
          },
          "spaceRemaining": {
            "type": "integer",
            "minimum": -1,
            "optional": true,
            "description": "The amount of remaining space on the cloud provider, in bytes. Set to <value>-1</value> if unsupported."
          },
          "spaceUsed": {
            "type": "integer",
            "minimum": -1,
            "optional": true,
            "description": "The amount of space already used on the cloud provider, in bytes. Set to <value>-1</value> if unsupported."
          },
          "managementUrl": {
            "type": "string",
            "format": "relativeUrl",
            "description": "A page for configuring accounts, to be displayed in the preferences UI."
          }
        }
      },
      {
        "id": "CloudFileTemplateInfo",
        "type": "object",
        "description": "Defines information to be used in the cloud file entry added to the message.",
        "properties": {
          "service_icon": {
            "type": "string",
            "optional": true,
            "description": "A URL pointing to an icon to represent the used cloud file service. Defaults to the icon of the provider add-on."
          },
          "service_name": {
            "type": "string",
            "optional": true,
            "description": "A name to represent the used cloud file service. Defaults to the associated cloud file account name."
          },
          "service_url": {
            "type": "string",
            "optional": true,
            "description": "A URL pointing to a web page of the used cloud file service. Will be used in a <em>Learn more about</em> link in the footer of the cloud file attachment element."
          },
          "download_password_protected": {
            "type": "boolean",
            "optional": true,
            "description": "If set to true, the cloud file entry for this upload will include a hint, that the download link is password protected."
          },
          "download_limit": {
            "type": "integer",
            "optional": true,
            "description": "If set, the cloud file entry for this upload will include a hint, that the file has a download limit."
          },
          "download_expiry_date": {
            "type": "object",
            "optional": true,
            "description": "If set, the cloud file entry for this upload will include a hint, that the link will only be available for a limited time.",
            "properties": {
              "timestamp": {
                "type": "integer",
                "description": "The expiry date of the link as the number of milliseconds since the UNIX epoch."
              },
              "format": {
                "optional": true,
                "description": "A format options object as used by |DateTimeFormat|. Defaults to: <literalinclude>includes/cloudFile/defaultDateFormat.js<lang>JavaScript</lang></literalinclude>",
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      {
        "id": "CloudFile",
        "type": "object",
        "description": "Information about a cloud file.",
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1,
            "description": "An identifier for this file."
          },
          "name": {
            "type": "string",
            "description": "Filename of the file to be transferred."
          },
          "data": {
            "type": "object",
            "isInstanceOf": "File",
            "additionalProperties": true,
            "description": "Contents of the file to be transferred."
          }
        }
      },
      {
        "id": "RelatedCloudFile",
        "type": "object",
        "description": "Information about an already uploaded cloud file, which is related to a new upload. For example if the content of a cloud attachment is updated, if a repeatedly used cloud attachment is renamed (and therefore should be re-uploaded to not invalidate existing links) or if the provider has its manifest property ``reuse_uploads`` set to <value>false</value>.",
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1,
            "optional": true,
            "description": "The identifier for the related file. In some circumstances, the id is unavailable."
          },
          "url": {
            "type": "string",
            "description": "The URL where the upload of the related file can be accessed.",
            "optional": true
          },
          "templateInfo": {
            "$ref": "CloudFileTemplateInfo",
            "description": "Additional information of the related file, used in the cloud file entry added to the message.",
            "optional": true
          },
          "name": {
            "type": "string",
            "description": "Filename of the related file."
          },
          "dataChanged": {
            "type": "boolean",
            "description": "The content of the new upload differs from the related file."
          }
        }
      }
    ],
    "functions": [
      {
        "name": "getAccount",
        "type": "function",
        "description": "Retrieve information about a single cloud file account.",
        "allowedContexts": ["content"],
        "async": "callback",
        "parameters": [
          {
            "name": "accountId",
            "type": "string",
            "description": "Unique identifier of the account."
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "$ref": "CloudFileAccount"
              }
            ]
          }
        ]
      },
      {
        "name": "getAllAccounts",
        "type": "function",
        "description": "Retrieve all cloud file accounts for the current add-on.",
        "allowedContexts": ["content"],
        "async": "callback",
        "parameters": [
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "type": "array",
                "items": {
                  "$ref": "CloudFileAccount"
                }
              }
            ]
          }
        ]
      },
      {
        "name": "updateAccount",
        "type": "function",
        "description": "Update a cloud file account.",
        "allowedContexts": ["content"],
        "async": "callback",
        "parameters": [
          {
            "name": "accountId",
            "type": "string",
            "description": "Unique identifier of the account."
          },
          {
            "name": "updateProperties",
            "type": "object",
            "properties": {
              "configured": {
                "type": "boolean",
                "optional": true,
                "description": "If true, the account is configured and ready to use. Only configured accounts are offered to the user."
              },
              "uploadSizeLimit": {
                "type": "integer",
                "minimum": -1,
                "optional": true,
                "description": "The maximum size in bytes for a single file to upload. Set to <value>-1</value> if unlimited."
              },
              "spaceRemaining": {
                "type": "integer",
                "minimum": -1,
                "optional": true,
                "description": "The amount of remaining space on the cloud provider, in bytes. Set to <value>-1</value> if unsupported."
              },
              "spaceUsed": {
                "type": "integer",
                "minimum": -1,
                "optional": true,
                "description": "The amount of space already used on the cloud provider, in bytes. Set to <value>-1</value> if unsupported."
              },
              "managementUrl": {
                "type": "string",
                "format": "relativeUrl",
                "optional": true,
                "description": "A page for configuring accounts, to be displayed in the preferences UI."
              }
            }
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "$ref": "CloudFileAccount"
              }
            ]
          }
        ]
      }
    ]
  }
]