Skip to content

Commit 378d63d

Browse files
erwanjuganderwanjugand
authored
🤖 Merge PR DefinitelyTyped#73395 [chrome] update cookies namespace by @erwanjugand 
1 parent 32a648f commit 378d63d

2 files changed

Lines changed: 117 additions & 79 deletions

File tree

‎types/chrome/index.d.ts‎

Lines changed: 66 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -2086,7 +2086,12 @@ declare namespace chrome {
20862086
*/
20872087
export namespace cookies {
20882088
/** A cookie's 'SameSite' state (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no_restriction' corresponds to a cookie set with 'SameSite=None', 'lax' to 'SameSite=Lax', and 'strict' to 'SameSite=Strict'. 'unspecified' corresponds to a cookie set without the SameSite attribute. **/
2089-
export type SameSiteStatus = "unspecified" | "no_restriction" | "lax" | "strict";
2089+
export enum SameSiteStatus {
2090+
NO_RESTRICTION = "no_restriction",
2091+
LAX = "lax",
2092+
STRICT = "strict",
2093+
UNSPECIFIED = "unspecified",
2094+
}
20902095

20912096
/** Represents information about an HTTP cookie. */
20922097
export interface Cookie {
@@ -2107,8 +2112,8 @@ declare namespace chrome {
21072112
session: boolean;
21082113
/** True if the cookie is a host-only cookie (i.e. a request's host must exactly match the domain of the cookie). */
21092114
hostOnly: boolean;
2110-
/** Optional. The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies. */
2111-
expirationDate?: number | undefined;
2115+
/** The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies. */
2116+
expirationDate?: number;
21122117
/** The path of the cookie. */
21132118
path: string;
21142119
/** True if the cookie is marked as HttpOnly (i.e. the cookie is inaccessible to client-side scripts). */
@@ -2119,10 +2124,13 @@ declare namespace chrome {
21192124
* The cookie's same-site status (i.e. whether the cookie is sent with cross-site requests).
21202125
* @since Chrome 51
21212126
*/
2122-
sameSite: SameSiteStatus;
2127+
sameSite: `${SameSiteStatus}`;
21232128
}
21242129

2125-
/** Represents a partitioned cookie's partition key. */
2130+
/**
2131+
* Represents a partitioned cookie's partition key.
2132+
* @since Chrome 119
2133+
*/
21262134
export interface CookiePartitionKey {
21272135
/**
21282136
* Indicates if the cookie was set in a cross-cross site context. This prevents a top-level site embedded in a cross-site context from accessing cookies set by the top-level site in a same-site context.
@@ -2142,31 +2150,31 @@ declare namespace chrome {
21422150
}
21432151

21442152
export interface GetAllDetails {
2145-
/** Optional. Restricts the retrieved cookies to those whose domains match or are subdomains of this one. */
2153+
/** Restricts the retrieved cookies to those whose domains match or are subdomains of this one. */
21462154
domain?: string | undefined;
2147-
/** Optional. Filters the cookies by name. */
2155+
/** Filters the cookies by name. */
21482156
name?: string | undefined;
21492157
/**
21502158
* The partition key for reading or modifying cookies with the Partitioned attribute.
21512159
* @since Chrome 119
21522160
*/
21532161
partitionKey?: CookiePartitionKey | undefined;
2154-
/** Optional. Restricts the retrieved cookies to those that would match the given URL. */
2162+
/** Restricts the retrieved cookies to those that would match the given URL. */
21552163
url?: string | undefined;
2156-
/** Optional. The cookie store to retrieve cookies from. If omitted, the current execution context's cookie store will be used. */
2164+
/** The cookie store to retrieve cookies from. If omitted, the current execution context's cookie store will be used. */
21572165
storeId?: string | undefined;
2158-
/** Optional. Filters out session vs. persistent cookies. */
2166+
/** Filters out session vs. persistent cookies. */
21592167
session?: boolean | undefined;
2160-
/** Optional. Restricts the retrieved cookies to those whose path exactly matches this string. */
2168+
/** Restricts the retrieved cookies to those whose path exactly matches this string. */
21612169
path?: string | undefined;
2162-
/** Optional. Filters the cookies by their Secure property. */
2170+
/** Filters the cookies by their Secure property. */
21632171
secure?: boolean | undefined;
21642172
}
21652173

21662174
export interface SetDetails {
2167-
/** Optional. The domain of the cookie. If omitted, the cookie becomes a host-only cookie. */
2175+
/** The domain of the cookie. If omitted, the cookie becomes a host-only cookie. */
21682176
domain?: string | undefined;
2169-
/** Optional. The name of the cookie. Empty by default if omitted. */
2177+
/** The name of the cookie. Empty by default if omitted. */
21702178
name?: string | undefined;
21712179
/**
21722180
* The partition key for reading or modifying cookies with the Partitioned attribute.
@@ -2175,26 +2183,29 @@ declare namespace chrome {
21752183
partitionKey?: CookiePartitionKey | undefined;
21762184
/** The request-URI to associate with the setting of the cookie. This value can affect the default domain and path values of the created cookie. If host permissions for this URL are not specified in the manifest file, the API call will fail. */
21772185
url: string;
2178-
/** Optional. The ID of the cookie store in which to set the cookie. By default, the cookie is set in the current execution context's cookie store. */
2186+
/** The ID of the cookie store in which to set the cookie. By default, the cookie is set in the current execution context's cookie store. */
21792187
storeId?: string | undefined;
2180-
/** Optional. The value of the cookie. Empty by default if omitted. */
2188+
/** The value of the cookie. Empty by default if omitted. */
21812189
value?: string | undefined;
2182-
/** Optional. The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted, the cookie becomes a session cookie. */
2190+
/** The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted, the cookie becomes a session cookie. */
21832191
expirationDate?: number | undefined;
2184-
/** Optional. The path of the cookie. Defaults to the path portion of the url parameter. */
2192+
/** The path of the cookie. Defaults to the path portion of the url parameter. */
21852193
path?: string | undefined;
2186-
/** Optional. Whether the cookie should be marked as HttpOnly. Defaults to false. */
2194+
/** Whether the cookie should be marked as HttpOnly. Defaults to false. */
21872195
httpOnly?: boolean | undefined;
2188-
/** Optional. Whether the cookie should be marked as Secure. Defaults to false. */
2196+
/** Whether the cookie should be marked as Secure. Defaults to false. */
21892197
secure?: boolean | undefined;
21902198
/**
2191-
* Optional. The cookie's same-site status. Defaults to "unspecified", i.e., if omitted, the cookie is set without specifying a SameSite attribute.
2199+
* The cookie's same-site status. Defaults to "unspecified", i.e., if omitted, the cookie is set without specifying a SameSite attribute.
21922200
* @since Chrome 51
21932201
*/
2194-
sameSite?: SameSiteStatus | undefined;
2202+
sameSite?: `${SameSiteStatus}` | undefined;
21952203
}
21962204

2197-
/** Details to identify the cookie. */
2205+
/**
2206+
* Details to identify the cookie.
2207+
* @since Chrome 88
2208+
*/
21982209
export interface CookieDetails {
21992210
/** The name of the cookie to access. */
22002211
name: string;
@@ -2214,11 +2225,8 @@ declare namespace chrome {
22142225
cookie: Cookie;
22152226
/** True if a cookie was removed. */
22162227
removed: boolean;
2217-
/**
2218-
* @since Chrome 12
2219-
* The underlying reason behind the cookie's change.
2220-
*/
2221-
cause: string;
2228+
/** The underlying reason behind the cookie's change. */
2229+
cause: `${OnChangedCause}`;
22222230
}
22232231

22242232
/**
@@ -2227,30 +2235,37 @@ declare namespace chrome {
22272235
*/
22282236
export interface FrameDetails {
22292237
/** The unique identifier for the document. If the frameId and/or tabId are provided they will be validated to match the document found by provided document ID. */
2230-
documentId?: string;
2238+
documentId?: string | undefined;
22312239
/** The unique identifier for the frame within the tab. */
2232-
frameId?: number;
2240+
frameId?: number | undefined;
22332241
/* The unique identifier for the tab containing the frame. */
2234-
tabId?: number;
2242+
tabId?: number | undefined;
22352243
}
22362244

2237-
export interface CookieChangedEvent extends chrome.events.Event<(changeInfo: CookieChangeInfo) => void> {}
2238-
22392245
/**
2240-
* Lists all existing cookie stores.
2241-
* Parameter cookieStores: All the existing cookie stores.
2246+
* The underlying reason behind the cookie's change. If a cookie was inserted, or removed via an explicit call to "chrome.cookies.remove", "cause" will be "explicit". If a cookie was automatically removed due to expiry, "cause" will be "expired". If a cookie was removed due to being overwritten with an already-expired expiration date, "cause" will be set to "expired_overwrite". If a cookie was automatically removed due to garbage collection, "cause" will be "evicted". If a cookie was automatically removed due to a "set" call that overwrote it, "cause" will be "overwrite". Plan your response accordingly.
2247+
* @since Chrome 44
22422248
*/
2243-
export function getAllCookieStores(callback: (cookieStores: CookieStore[]) => void): void;
2249+
export enum OnChangedCause {
2250+
EVICTED = "evicted",
2251+
EXPIRED = "expired",
2252+
EXPLICIT = "explicit",
2253+
EXPIRED_OVERWRITE = "expired_overwrite",
2254+
OVERWRITE = "overwrite",
2255+
}
22442256

22452257
/**
22462258
* Lists all existing cookie stores.
2247-
* @return The `getAllCookieStores` method provides its result via callback or returned as a `Promise` (MV3 only).
2259+
*
2260+
* Can return its result via Promise in Manifest V3 or later.
22482261
*/
22492262
export function getAllCookieStores(): Promise<CookieStore[]>;
2263+
export function getAllCookieStores(callback: (cookieStores: CookieStore[]) => void): void;
22502264

22512265
/**
22522266
* The partition key for the frame indicated.
2253-
* Can return its result via Promise in Manifest V3
2267+
*
2268+
* Can return its result via Promise in Manifest V3 or later.
22542269
* @since Chrome 132
22552270
*/
22562271
export function getPartitionKey(details: FrameDetails): Promise<{ partitionKey: CookiePartitionKey }>;
@@ -2260,62 +2275,41 @@ declare namespace chrome {
22602275
): void;
22612276

22622277
/**
2263-
* Retrieves all cookies from a single cookie store that match the given information. The cookies returned will be sorted, with those with the longest path first. If multiple cookies have the same path length, those with the earliest creation time will be first.
2264-
* @param details Information to filter the cookies being retrieved.
2265-
* Parameter cookies: All the existing, unexpired cookies that match the given cookie info.
2266-
*/
2267-
export function getAll(details: GetAllDetails, callback: (cookies: Cookie[]) => void): void;
2268-
2269-
/**
2270-
* Retrieves all cookies from a single cookie store that match the given information. The cookies returned will be sorted, with those with the longest path first. If multiple cookies have the same path length, those with the earliest creation time will be first.
2271-
* @param details Information to filter the cookies being retrieved.
2272-
* @return The `getAll` method provides its result via callback or returned as a `Promise` (MV3 only).
2278+
* Retrieves all cookies from a single cookie store that match the given information. The cookies returned will be sorted, with those with the longest path first. If multiple cookies have the same path length, those with the earliest creation time will be first. This method only retrieves cookies for domains that the extension has host permissions to
2279+
* @param details Information to identify the cookie to remove.
2280+
*
2281+
* Can return its result via Promise in Manifest V3 or later.
22732282
*/
22742283
export function getAll(details: GetAllDetails): Promise<Cookie[]>;
2284+
export function getAll(details: GetAllDetails, callback: (cookies: Cookie[]) => void): void;
22752285

22762286
/**
22772287
* Sets a cookie with the given cookie data; may overwrite equivalent cookies if they exist.
22782288
* @param details Details about the cookie being set.
2279-
* @return The `set` method provides its result via callback or returned as a `Promise` (MV3 only).
2289+
*
2290+
* Can return its result via Promise in Manifest V3 or later.
22802291
*/
22812292
export function set(details: SetDetails): Promise<Cookie | null>;
2282-
2283-
/**
2284-
* Sets a cookie with the given cookie data; may overwrite equivalent cookies if they exist.
2285-
* @param details Details about the cookie being set.
2286-
* Optional parameter cookie: Contains details about the cookie that's been set. If setting failed for any reason, this will be "null", and "chrome.runtime.lastError" will be set.
2287-
*/
22882293
export function set(details: SetDetails, callback: (cookie: Cookie | null) => void): void;
22892294

22902295
/**
22912296
* Deletes a cookie by name.
2292-
* @param details Information to identify the cookie to remove.
2293-
* @return The `remove` method provides its result via callback or returned as a `Promise` (MV3 only).
2297+
*
2298+
* Can return its result via Promise in Manifest V3 or later.
22942299
*/
22952300
export function remove(details: CookieDetails): Promise<CookieDetails>;
2296-
2297-
/**
2298-
* Deletes a cookie by name.
2299-
* @param details Information to identify the cookie to remove.
2300-
*/
23012301
export function remove(details: CookieDetails, callback?: (details: CookieDetails) => void): void;
23022302

23032303
/**
23042304
* Retrieves information about a single cookie. If more than one cookie of the same name exists for the given URL, the one with the longest path will be returned. For cookies with the same path length, the cookie with the earliest creation time will be returned.
2305-
* @param details Details to identify the cookie being retrieved.
2306-
* Parameter cookie: Contains details about the cookie. This parameter is null if no such cookie was found.
2307-
*/
2308-
export function get(details: CookieDetails, callback: (cookie: Cookie | null) => void): void;
2309-
2310-
/**
2311-
* Retrieves information about a single cookie. If more than one cookie of the same name exists for the given URL, the one with the longest path will be returned. For cookies with the same path length, the cookie with the earliest creation time will be returned.
2312-
* @param details Details to identify the cookie being retrieved.
2313-
* @return The `get` method provides its result via callback or returned as a `Promise` (MV3 only).
2305+
*
2306+
* Can return its result via Promise in Manifest V3 or later.
23142307
*/
23152308
export function get(details: CookieDetails): Promise<Cookie | null>;
2309+
export function get(details: CookieDetails, callback: (cookie: Cookie | null) => void): void;
23162310

23172311
/** Fired when a cookie is set or removed. As a special case, note that updating a cookie's properties is implemented as a two step process: the cookie to be updated is first removed entirely, generating a notification with "cause" of "overwrite" . Afterwards, a new cookie is written with the updated values, generating a second notification with "cause" "explicit". */
2318-
export var onChanged: CookieChangedEvent;
2312+
export const onChanged: events.Event<(changeInfo: CookieChangeInfo) => void>;
23192313
}
23202314

23212315
////////////////////

‎types/chrome/test/index.ts‎

Lines changed: 51 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1972,13 +1972,25 @@ async function testBrowserActionForPromise() {
19721972

19731973
// https://developer.chrome.com/docs/extensions/reference/api/cookies
19741974
async function testCookie() {
1975+
chrome.cookies.OnChangedCause.EVICTED === "evicted";
1976+
chrome.cookies.OnChangedCause.EXPIRED === "expired";
1977+
chrome.cookies.OnChangedCause.EXPIRED_OVERWRITE === "expired_overwrite";
1978+
chrome.cookies.OnChangedCause.EXPLICIT === "explicit";
1979+
chrome.cookies.OnChangedCause.OVERWRITE === "overwrite";
1980+
1981+
chrome.cookies.SameSiteStatus.LAX === "lax";
1982+
chrome.cookies.SameSiteStatus.NO_RESTRICTION === "no_restriction";
1983+
chrome.cookies.SameSiteStatus.STRICT === "strict";
1984+
chrome.cookies.SameSiteStatus.UNSPECIFIED === "unspecified";
1985+
19751986
const cookieDetails: chrome.cookies.CookieDetails = {
19761987
url: "https://example.com",
19771988
name: "example",
19781989
partitionKey: {
19791990
topLevelSite: "https://example.com",
19801991
hasCrossSiteAncestor: false,
19811992
},
1993+
storeId: "storeId1",
19821994
};
19831995

19841996
chrome.cookies.get(cookieDetails); // $ExpectType Promise<Cookie | null>
@@ -1988,12 +2000,26 @@ async function testCookie() {
19882000
// @ts-expect-error
19892001
chrome.cookies.get(cookieDetails, () => {}).then(() => {});
19902002

1991-
chrome.cookies.getAll(cookieDetails); // $ExpectType Promise<Cookie[]>
1992-
chrome.cookies.getAll(cookieDetails, (cookies) => {
2003+
const cookiesAllDetails: chrome.cookies.GetAllDetails = {
2004+
domain: "example.com",
2005+
name: "example",
2006+
partitionKey: {
2007+
topLevelSite: "https://example.com",
2008+
hasCrossSiteAncestor: false,
2009+
},
2010+
path: "/",
2011+
secure: true,
2012+
session: true,
2013+
storeId: "storeId1",
2014+
url: "https://example.com",
2015+
};
2016+
2017+
chrome.cookies.getAll(cookiesAllDetails); // $ExpectType Promise<Cookie[]>
2018+
chrome.cookies.getAll(cookiesAllDetails, (cookies) => {
19932019
cookies; // $ExpectType Cookie[]
19942020
});
19952021
// @ts-expect-error
1996-
chrome.cookies.getAll(cookieDetails, () => {}).then(() => {});
2022+
chrome.cookies.getAll(cookiesAllDetails, () => {}).then(() => {});
19972023

19982024
chrome.cookies.getAllCookieStores(); // $ExpectType Promise<CookieStore[]>
19992025
chrome.cookies.getAllCookieStores((cookieStores) => {
@@ -2020,15 +2046,33 @@ async function testCookie() {
20202046
// @ts-expect-error
20212047
chrome.cookies.remove(cookieDetails, () => {}).then(() => {});
20222048

2023-
chrome.cookies.set(cookieDetails); // $ExpectType Promise<Cookie | null>
2024-
chrome.cookies.set(cookieDetails, (cookie) => {
2049+
const cookieDetailsSet: chrome.cookies.SetDetails = {
2050+
domain: "example.com",
2051+
expirationDate: 1717334400,
2052+
httpOnly: true,
2053+
name: "example",
2054+
partitionKey: {
2055+
topLevelSite: "https://example.com",
2056+
hasCrossSiteAncestor: false,
2057+
},
2058+
path: "/",
2059+
sameSite: "strict",
2060+
secure: true,
2061+
url: "https://example.com",
2062+
value: "value1",
2063+
};
2064+
2065+
chrome.cookies.set(cookieDetailsSet); // $ExpectType Promise<Cookie | null>
2066+
chrome.cookies.set(cookieDetailsSet, (cookie) => {
20252067
cookie; // $ExpectType Cookie | null
20262068
});
20272069
// @ts-expect-error
2028-
chrome.cookies.set(cookieDetails, () => {}).then(() => {});
2070+
chrome.cookies.set(cookieDetailsSet, () => {}).then(() => {});
20292071

20302072
checkChromeEvent(chrome.cookies.onChanged, (changeInfo) => {
2031-
changeInfo; // $ExpectType CookieChangeInfo
2073+
changeInfo.cause; // $ExpectType "evicted" | "expired" | "explicit" | "expired_overwrite" | "overwrite"
2074+
changeInfo.cookie; // $ExpectType Cookie
2075+
changeInfo.removed; // $ExpectType boolean
20322076
});
20332077
}
20342078

0 commit comments

Comments
 (0)