// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

[
  {
    "namespace": "bookmarks",
    "description": "Use the <code>chrome.bookmarks</code> API to create, organize, and otherwise manipulate bookmarks. Also see <a href='override'>Override Pages</a>, which you can use to create a custom Bookmark Manager page.",
    "properties": {
      "MAX_WRITE_OPERATIONS_PER_HOUR": {
        "value": 1000000,
        "deprecated": "Bookmark write operations are no longer limited by Chrome.",
        "description": ""
      },
      "MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE": {
        "value": 1000000,
        "deprecated": "Bookmark write operations are no longer limited by Chrome.",
        "description": ""
      },
      "ROOT_NODE_ID": {
        "value": "0",
        "description": "The <code>id</code> associated with the root level node."
      }
    },
    "types": [
      {
        "id": "FolderType",
        "type": "string",
        "enum": [{
          "name": "bookmarks-bar",
          "description": "The folder whose contents is displayed at the top of the browser window."
        }, {
          "name": "other",
          "description": "Bookmarks which are displayed in the full list of bookmarks on all platforms."
        }, {
          "name": "mobile",
          "description": "Bookmarks generally available on the user's mobile devices, but modifiable by extension or in the bookmarks manager."
        }, {
          "name": "managed",
          "description": "A top-level folder that may be present if the system administrator or the custodian of a supervised user has configured bookmarks."
        }],
        "description": "Indicates the type of folder."
      },
      {
        "id": "BookmarkTreeNodeUnmodifiable",
        "type": "string",
        "enum": ["managed"],
        "description": "Indicates the reason why this node is unmodifiable. The <var>managed</var> value indicates that this node was configured by the system administrator. Omitted if the node can be modified by the user and the extension (default)."
      },
      {
        "id": "BookmarkTreeNode",
        "type": "object",
        "description": "A node (either a bookmark or a folder) in the bookmark tree.  Child nodes are ordered within their parent folder.",
        "properties": {
          "id": {
            "type": "string",
            "minimum": 0,
            "description": "The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the browser is restarted."
          },
          "parentId": {
            "type": "string",
            "minimum": 0,
            "optional": true,
            "description": "The <code>id</code> of the parent folder.  Omitted for the root node."
          },
          "index": {
            "type": "integer",
            "optional": true,
            "description": "The 0-based position of this node within its parent folder."
          },
          "url": {
            "type": "string",
            "optional": true,
            "description": "The URL navigated to when a user clicks the bookmark. Omitted for folders."
          },
          "title": {
            "type": "string",
            "description": "The text displayed for the node."
          },
          "dateAdded": {
            "type": "number",
            "optional": true,
            "description": "When this node was created, in milliseconds since the epoch (<code>new Date(dateAdded)</code>)."
          },
          "dateLastUsed": {
            "type": "number",
            "optional": true,
            "description": "When this node was last opened, in milliseconds since the epoch. Not set for folders."
          },
          "dateGroupModified": {
            "type": "number",
            "optional": true,
            "description": "When the contents of this folder last changed, in milliseconds since the epoch."
          },
          "folderType": {
            "$ref": "FolderType",
            "optional": true,
            "description": "If present, this is a folder that is added by the browser and that cannot be modified by the user or the extension. Child nodes may be modified, if this node does not have the <code>unmodifiable</code> property set. Omitted if the node can be modified by the user and the extension (default).<p>There may be zero, one or multiple nodes of each folder type. A folder may be added or removed by the browser, but not via the extensions API."
          },
          "unmodifiable": {
            "$ref": "BookmarkTreeNodeUnmodifiable",
            "optional": true,
            "description": "Indicates the reason why this node is unmodifiable. The <var>managed</var> value indicates that this node was configured by the system administrator or by the custodian of a supervised user. Omitted if the node can be modified by the user and the extension (default)."
          },
          "syncing": {
            "type": "boolean",
            "description": "Whether this node is synced with the user's remote account storage by the browser. This can be used to distinguish between account and local-only versions of the same $(ref:FolderType). The value of this property may change for an existing node, for example as a result of user action.<p>Note: this reflects whether the node is saved to the browser's built-in account provider. It is possible that a node could be synced via a third-party, even if this value is false.</p><p>For managed nodes (nodes where <code>unmodifiable</code> is set to <code>true</code>), this property will always be <code>false</code>.</p>"
          },
          "children": {
            "type": "array",
            "optional": true,
            "items": { "$ref": "BookmarkTreeNode" },
            "description": "An ordered list of children of this node."
          }
        }
      },
      {
        "id": "CreateDetails",
        "description": "Object passed to the create() function.",
        "type": "object",
        "properties": {
          "parentId": {
            "type": "string",
            "optional": true,
            "description": "Defaults to the Other Bookmarks folder."
          },
          "index": {
            "type": "integer",
            "minimum": 0,
            "optional": true
          },
          "title": {
            "type": "string",
            "optional": true
          },
          "url": {
            "type": "string",
            "optional": true
          }
        }
      }
    ],
    "functions": [
      {
        "name": "get",
        "type": "function",
        "description": "Retrieves the specified BookmarkTreeNode(s).",
        "parameters": [
          {
            "name": "idOrIdList",
            "description": "A single string-valued id, or an array of string-valued ids",
            "choices": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 1
              }
            ]
          }
        ],
        "returns_async": {
          "name": "callback",
          "parameters": [
            {
              "name": "results",
              "type": "array",
              "items": { "$ref": "BookmarkTreeNode" }
            }
          ]
        }
      },
      {
        "name": "getChildren",
        "type": "function",
        "description": "Retrieves the children of the specified BookmarkTreeNode id.",
        "parameters": [
          {
            "type": "string",
            "name": "id"
          }
        ],
        "returns_async": {
          "name": "callback",
          "parameters": [
            {
              "name": "results",
              "type": "array",
              "items": { "$ref": "BookmarkTreeNode"}
            }
          ]
        }
      },
      {
        "name": "getRecent",
        "type": "function",
        "description": "Retrieves the recently added bookmarks.",
        "parameters": [
          {
            "type": "integer",
            "minimum": 1,
            "name": "numberOfItems",
            "description": "The maximum number of items to return."
          }
        ],
        "returns_async": {
          "name": "callback",
          "parameters": [
            {
              "name": "results",
              "type": "array",
              "items": { "$ref": "BookmarkTreeNode" }
            }
          ]
        }
      },
      {
        "name": "getTree",
        "type": "function",
        "description": "Retrieves the entire Bookmarks hierarchy.",
        "parameters": [],
        "returns_async": {
          "name": "callback",
          "parameters": [
            {
              "name": "results",
              "type": "array",
              "items": { "$ref": "BookmarkTreeNode" }
            }
          ]
        }
      },
      {
        "name": "getSubTree",
        "type": "function",
        "description": "Retrieves part of the Bookmarks hierarchy, starting at the specified node.",
        "parameters": [
          {
            "type": "string",
            "name": "id",
            "description": "The ID of the root of the subtree to retrieve."
          }
        ],
        "returns_async": {
          "name": "callback",
          "parameters": [
            {
              "name": "results",
              "type": "array",
              "items": { "$ref": "BookmarkTreeNode" }
            }
          ]
        }
      },
      {
        "name": "search",
        "type": "function",
        "description": "Searches for BookmarkTreeNodes matching the given query. Queries specified with an object produce BookmarkTreeNodes matching all specified properties.",
        "parameters": [
          {
            "name": "query",
            "description": "Either a string of words and quoted phrases that are matched against bookmark URLs and titles, or an object. If an object, the properties <code>query</code>, <code>url</code>, and <code>title</code> may be specified and bookmarks matching all specified properties will be produced.",
            "choices": [
              {
                "type": "string",
                "description": "A string of words and quoted phrases that are matched against bookmark URLs and titles."
              },
              {
                "type": "object",
                "description": "An object specifying properties and values to match when searching. Produces bookmarks matching all properties.",
                "properties": {
                  "query": {
                    "type": "string",
                    "optional": true,
                    "description": "A string of words and quoted phrases that are matched against bookmark URLs and titles."
                  },
                  "url": {
                    "type": "string",
                    "optional": true,
                    "description": "The URL of the bookmark; matches verbatim. Note that folders have no URL."
                  },
                  "title": {
                    "type": "string",
                    "optional": true,
                    "description": "The title of the bookmark; matches verbatim."
                  }
                }
              }
            ]
          }
        ],
        "returns_async": {
          "name": "callback",
          "parameters": [
            {
              "name": "results",
              "type": "array",
              "items": { "$ref": "BookmarkTreeNode" }
            }
          ]
        }
      },
      {
        "name": "create",
        "type": "function",
        "description": "Creates a bookmark or folder under the specified parentId.  If url is NULL or missing, it will be a folder.",
        "parameters": [
          {
            "$ref": "CreateDetails",
            "name": "bookmark"
          }
        ],
        "returns_async": {
          "name": "callback",
          "optional": true,
          "parameters": [
            {
              "name": "result",
              "$ref": "BookmarkTreeNode"
            }
          ]
        }
      },
      {
        "name": "move",
        "type": "function",
        "description": "Moves the specified BookmarkTreeNode to the provided location.",
        "parameters": [
          {
            "type": "string",
            "name": "id"
          },
          {
            "type": "object",
            "name": "destination",
            "properties": {
              "parentId": {
                "type": "string",
                "optional": true
              },
              "index": {
                "type": "integer",
                "minimum": 0,
                "optional": true
              }
            }
          }
        ],
        "returns_async": {
          "name": "callback",
          "optional": true,
          "parameters": [
            {
              "name": "result",
              "$ref": "BookmarkTreeNode"
            }
          ]
        }
      },
      {
        "name": "update",
        "type": "function",
        "description": "Updates the properties of a bookmark or folder. Specify only the properties that you want to change; unspecified properties will be left unchanged.  <b>Note:</b> Currently, only 'title' and 'url' are supported.",
        "parameters": [
          {
            "type": "string",
            "name": "id"
          },
          {
            "type": "object",
            "name": "changes",
            "properties": {
              "title": {
                "type": "string",
                "optional": true
              },
              "url": {
                "type": "string",
                "optional": true
              }
            }
          }
        ],
        "returns_async": {
          "name": "callback",
          "optional": true,
          "parameters": [
            {
              "name": "result",
              "$ref": "BookmarkTreeNode"
            }
          ]
        }
      },
      {
        "name": "remove",
        "type": "function",
        "description": "Removes a bookmark or an empty bookmark folder.",
        "parameters": [
          {
            "type": "string",
            "name": "id"
          }
        ],
        "returns_async": {
          "name": "callback",
          "optional": true,
          "parameters": []
        }
      },
      {
        "name": "removeTree",
        "type": "function",
        "description": "Recursively removes a bookmark folder.",
        "parameters": [
          {
            "type": "string",
            "name": "id"
          }
        ],
        "returns_async": {
          "name": "callback",
          "optional": true,
          "parameters": []
        }
      }
    ],
    "events": [
      {
        "name": "onCreated",
        "type": "function",
        "description": "Fired when a bookmark or folder is created.",
        "parameters": [
          {
            "type": "string",
            "name": "id"
          },
          {
            "$ref": "BookmarkTreeNode",
            "name": "bookmark"
          }
        ]
      },
      {
        "name": "onRemoved",
        "type": "function",
        "description": "Fired when a bookmark or folder is removed.  When a folder is removed recursively, a single notification is fired for the folder, and none for its contents.",
        "parameters": [
          {
            "type": "string",
            "name": "id"
          },
          {
            "type": "object",
            "name": "removeInfo",
            "properties": {
              "parentId": { "type": "string" },
              "index": { "type": "integer" },
              "node": { "$ref": "BookmarkTreeNode" }
            }
          }
        ]
      },
      {
        "name": "onChanged",
        "type": "function",
        "description": "Fired when a bookmark or folder changes.  <b>Note:</b> Currently, only title and url changes trigger this.",
        "parameters": [
          {
            "type": "string",
            "name": "id"
          },
          {
            "type": "object",
            "name": "changeInfo",
            "properties": {
              "title": { "type": "string" },
              "url": {
                "type": "string",
                "optional": true
              }
            }
          }
        ]
      },
      {
        "name": "onMoved",
        "type": "function",
        "description": "Fired when a bookmark or folder is moved to a different parent folder.",
        "parameters": [
          {
            "type": "string",
            "name": "id"
          },
          {
            "type": "object",
            "name": "moveInfo",
            "properties": {
              "parentId": { "type": "string" },
              "index": { "type": "integer" },
              "oldParentId": { "type": "string" },
              "oldIndex": { "type": "integer" }
            }
          }
        ]
      },
      {
        "name": "onChildrenReordered",
        "type": "function",
        "description": "Fired when the children of a folder have changed their order due to the order being sorted in the UI.  This is not called as a result of a move().",
        "parameters": [
          {
            "type": "string",
            "name": "id"
          },
          {
            "type": "object",
            "name": "reorderInfo",
            "properties": {
              "childIds": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          }
        ]
      },
      {
        "name": "onImportBegan",
        "type": "function",
        "description": "Fired when a bookmark import session is begun.  Expensive observers should ignore onCreated updates until onImportEnded is fired.  Observers should still handle other notifications immediately.",
        "parameters": []
      },
      {
        "name": "onImportEnded",
        "type": "function",
        "description": "Fired when a bookmark import session is ended.",
        "parameters": []
      }
    ]
  }
]