@taskeren/bungie-api-ts 5.10.0

package/generated-src/user/interfaces.ts

@@ -0,0 +1,338 @@
+/**
+ * Bungie.Net API
+ * These endpoints constitute the functionality exposed by Bungie.net, both for more traditional website functionality and for connectivity to Bungie video games and their related functionality.
+ *
+ * OpenAPI spec version: 2.21.9
+ * Contact: support@bungie.com
+ *
+ * NOTE: This class is auto generated by the bungie-api-ts code generator program.
+ * https://github.com/DestinyItemManager/bungie-api-ts
+ * Do not edit these files manually.
+ */
+
+import {
+  BungieMembershipType
+} from '../common.js';
+import {
+  GroupUserInfoCard
+} from '../groupv2/interfaces.js';
+import {
+  IgnoreResponse
+} from '../platform.js';
+
+/**
+ * This contract supplies basic information commonly used to display a minimal
+ * amount of information about a user. Take care to not add more properties here
+ * unless the property applies in all (or at least the majority) of the situations
+ * where UserInfoCard is used. Avoid adding game specific or platform specific
+ * details here. In cases where UserInfoCard is a subset of the data needed in a
+ * contract, use UserInfoCard as a property of other contracts.
+ */
+export interface UserInfoCard {
+  /**
+   * A platform specific additional display name - ex: psn Real Name, bnet Unique
+   * Name, etc.
+   */
+  readonly supplementalDisplayName: string;
+  /** URL the Icon if available. */
+  readonly iconPath: string;
+  /**
+   * If there is a cross save override in effect, this value will tell you the type
+   * that is overridding this one.
+   */
+  readonly crossSaveOverride: BungieMembershipType;
+  /**
+   * The list of Membership Types indicating the platforms on which this Membership
+   * can be used.
+   *
+   * Not in Cross Save = its original membership type. Cross Save Primary = Any
+   * membership types it is overridding, and its original membership type Cross Save
+   * Overridden = Empty list
+   */
+  readonly applicableMembershipTypes: BungieMembershipType[];
+  /** If True, this is a public user membership. */
+  readonly isPublic: boolean;
+  /** Type of the membership. Not necessarily the native type. */
+  readonly membershipType: BungieMembershipType;
+  /** Membership ID as they user is known in the Accounts service */
+  readonly membershipId: string;
+  /**
+   * Display Name the player has chosen for themselves. The display name is optional
+   * when the data type is used as input to a platform API.
+   */
+  readonly displayName: string;
+  /** The bungie global display name, if set. */
+  readonly bungieGlobalDisplayName: string;
+  /** The bungie global display name code, if set. */
+  readonly bungieGlobalDisplayNameCode?: number;
+}
+
+/**
+ * The types of credentials the Accounts system supports. This is the external
+ * facing enum used in place of the internal-only Bungie.SharedDefinitions.
+ * CredentialType.
+ */
+export const enum BungieCredentialType {
+  None = 0,
+  Xuid = 1,
+  Psnid = 2,
+  Wlid = 3,
+  Fake = 4,
+  Facebook = 5,
+  Google = 8,
+  Windows = 9,
+  DemonId = 10,
+  SteamId = 12,
+  BattleNetId = 14,
+  StadiaId = 16,
+  TwitchId = 18,
+  EgsId = 20
+}
+
+export interface UserSearchPrefixRequest {
+  readonly displayNamePrefix: string;
+}
+
+export interface GeneralUser {
+  readonly membershipId: string;
+  readonly uniqueName: string;
+  readonly normalizedName: string;
+  readonly displayName: string;
+  readonly profilePicture: number;
+  readonly profileTheme: number;
+  readonly userTitle: number;
+  readonly successMessageFlags: string;
+  readonly isDeleted: boolean;
+  readonly about: string;
+  readonly firstAccess?: string;
+  readonly lastUpdate?: string;
+  readonly legacyPortalUID?: string;
+  readonly context: UserToUserContext;
+  readonly psnDisplayName: string;
+  readonly xboxDisplayName: string;
+  readonly fbDisplayName: string;
+  readonly showActivity?: boolean;
+  readonly locale: string;
+  readonly localeInheritDefault: boolean;
+  readonly lastBanReportId?: string;
+  readonly showGroupMessaging: boolean;
+  readonly profilePicturePath: string;
+  readonly profilePictureWidePath: string;
+  readonly profileThemeName: string;
+  readonly userTitleDisplay: string;
+  readonly statusText: string;
+  readonly statusDate: string;
+  readonly profileBanExpire?: string;
+  readonly blizzardDisplayName: string;
+  readonly steamDisplayName: string;
+  readonly stadiaDisplayName: string;
+  readonly twitchDisplayName: string;
+  readonly cachedBungieGlobalDisplayName: string;
+  readonly cachedBungieGlobalDisplayNameCode?: number;
+  readonly egsDisplayName: string;
+}
+
+export interface UserToUserContext {
+  readonly isFollowing: boolean;
+  readonly ignoreStatus: IgnoreResponse;
+  readonly globalIgnoreEndDate?: string;
+}
+
+export interface GetCredentialTypesForAccountResponse {
+  readonly credentialType: BungieCredentialType;
+  readonly credentialDisplayName: string;
+  readonly isPublic: boolean;
+  readonly credentialAsString: string;
+}
+
+export interface UserTheme {
+  readonly userThemeId: number;
+  readonly userThemeName: string;
+  readonly userThemeDescription: string;
+}
+
+export interface UserMembershipData {
+  /**
+   * this allows you to see destiny memberships that are visible and linked to this
+   * account (regardless of whether or not they have characters on the world server)
+   */
+  readonly destinyMemberships: GroupUserInfoCard[];
+  /**
+   * If this property is populated, it will have the membership ID of the account
+   * considered to be "primary" in this user's cross save relationship.
+   *
+   * If null, this user has no cross save relationship, nor primary account.
+   */
+  readonly primaryMembershipId?: string;
+  /**
+   * If this property is populated, it will have the membershipId for the Marathon
+   * Membership on this user's account
+   *
+   * If null, this user has no Marathon (i.e. "GoliathGame") membership.
+   */
+  readonly marathonMembershipId?: string;
+  readonly bungieNetUser: GeneralUser;
+}
+
+export interface HardLinkedUserMembership {
+  readonly membershipType: BungieMembershipType;
+  readonly membershipId: string;
+  readonly CrossSaveOverriddenType: BungieMembershipType;
+  readonly CrossSaveOverriddenMembershipId?: string;
+}
+
+export interface UserSearchResponse {
+  readonly searchResults: UserSearchResponseDetail[];
+  readonly page: number;
+  readonly hasMore: boolean;
+}
+
+export interface UserSearchResponseDetail {
+  readonly bungieGlobalDisplayName: string;
+  readonly bungieGlobalDisplayNameCode?: number;
+  readonly bungieNetMembershipId?: string;
+  readonly destinyMemberships: UserInfoCard[];
+}
+
+/** Very basic info about a user as returned by the Account server. */
+export interface UserMembership {
+  /** Type of the membership. Not necessarily the native type. */
+  readonly membershipType: BungieMembershipType;
+  /** Membership ID as they user is known in the Accounts service */
+  readonly membershipId: string;
+  /**
+   * Display Name the player has chosen for themselves. The display name is optional
+   * when the data type is used as input to a platform API.
+   */
+  readonly displayName: string;
+  /** The bungie global display name, if set. */
+  readonly bungieGlobalDisplayName: string;
+  /** The bungie global display name code, if set. */
+  readonly bungieGlobalDisplayNameCode?: number;
+}
+
+export interface ExactSearchRequest {
+  readonly displayName: string;
+  readonly displayNameCode: number;
+}
+
+/** The set of all email subscription/opt-in settings and definitions. */
+export interface EmailSettings {
+  /** Keyed by the name identifier of the opt-in definition. */
+  readonly optInDefinitions: { [key: string]: EmailOptInDefinition };
+  /** Keyed by the name identifier of the Subscription definition. */
+  readonly subscriptionDefinitions: { [key: string]: EmailSubscriptionDefinition };
+  /** Keyed by the name identifier of the View definition. */
+  readonly views: { [key: string]: EmailViewDefinition };
+}
+
+/**
+ * Defines a single opt-in category: a wide-scoped permission to send emails for
+ * the subject related to the opt-in.
+ */
+export interface EmailOptInDefinition {
+  /** The unique identifier for this opt-in category. */
+  readonly name: string;
+  /**
+   * The flag value for this opt-in category. For historical reasons, this is defined
+   * as a flags enum.
+   *
+   * This enum represents a set of flags - use bitwise operators to check which of
+   * these match your value.
+   */
+  readonly value: OptInFlags;
+  /**
+   * If true, this opt-in setting should be set by default in situations where
+   * accounts are created without explicit choices about what they're opting into.
+   */
+  readonly setByDefault: boolean;
+  /** Information about the dependent subscriptions for this opt-in. */
+  readonly dependentSubscriptions: EmailSubscriptionDefinition[];
+}
+
+/**
+ * This enum represents a set of flags - use bitwise operators to check which of
+ * these match your value.
+ */
+export const enum OptInFlags {
+  None = 0,
+  Newsletter = 1,
+  System = 2,
+  Marketing = 4,
+  UserResearch = 8,
+  CustomerService = 16,
+  Social = 32,
+  PlayTests = 64,
+  PlayTestsLocal = 128,
+  Careers = 256
+}
+
+/**
+ * Defines a single subscription: permission to send emails for a specific, focused
+ * subject (generally timeboxed, such as for a specific release of a product or
+ * feature).
+ */
+export interface EmailSubscriptionDefinition {
+  /** The unique identifier for this subscription. */
+  readonly name: string;
+  /** A dictionary of localized text for the EMail Opt-in setting, keyed by the locale. */
+  readonly localization: { [key: string]: EMailSettingSubscriptionLocalization };
+  /** The bitflag value for this subscription. Should be a unique power of two value. */
+  readonly value: string;
+}
+
+/**
+ * Localized text relevant to a given EMail setting in a given localization. Extra
+ * settings specifically for subscriptions.
+ */
+export interface EMailSettingSubscriptionLocalization {
+  readonly unknownUserDescription: string;
+  readonly registeredUserDescription: string;
+  readonly unregisteredUserDescription: string;
+  readonly unknownUserActionText: string;
+  readonly knownUserActionText: string;
+  readonly title: string;
+  readonly description: string;
+}
+
+/**
+ * Represents a data-driven view for Email settings. Web/Mobile UI can use this
+ * data to show new EMail settings consistently without further manual work.
+ */
+export interface EmailViewDefinition {
+  /** The identifier for this view. */
+  readonly name: string;
+  /** The ordered list of settings to show in this view. */
+  readonly viewSettings: EmailViewDefinitionSetting[];
+}
+
+export interface EmailViewDefinitionSetting {
+  /**
+   * The identifier for this UI Setting, which can be used to relate it to custom
+   * strings or other data as desired.
+   */
+  readonly name: string;
+  /** A dictionary of localized text for the EMail setting, keyed by the locale. */
+  readonly localization: { [key: string]: EMailSettingLocalization };
+  /**
+   * If true, this setting should be set by default if the user hasn't chosen whether
+   * it's set or cleared yet.
+   */
+  readonly setByDefault: boolean;
+  /**
+   * The OptInFlags value to set or clear if this setting is set or cleared in the UI.
+   * It is the aggregate of all underlying opt-in flags related to this setting.
+   *
+   * This enum represents a set of flags - use bitwise operators to check which of
+   * these match your value.
+   */
+  readonly optInAggregateValue: OptInFlags;
+  /** The subscriptions to show as children of this setting, if any. */
+  readonly subscriptions: EmailSubscriptionDefinition[];
+}
+
+/** Localized text relevant to a given EMail setting in a given localization. */
+export interface EMailSettingLocalization {
+  readonly title: string;
+  readonly description: string;
+}

package/generator/generate-api.ts

@@ -0,0 +1,254 @@
+import {
+  DefInfo,
+  getRef,
+  isReferenceObject,
+  isRequestBodyObject,
+  lastPart,
+  lcFirst,
+  resolveSchemaType,
+} from './util.js';
+import { OpenAPIObject, ParameterObject, PathItemObject } from 'openapi3-ts';
+import {
+  addImport,
+  docComment,
+  generateHeader,
+  generateImports,
+  indent,
+  writeOutFile,
+} from './generate-common.js';
+
+const httpClientType = `import { HttpClient, get, post } from '../http.js';`;
+
+/**
+ * Generate an api.ts file for a particular "service", which is defined by a specific tag on the path entry
+ * in the OpenAPI spec. e.g. all the User service paths have the tag "User".
+ */
+export function generateServiceDefinition(
+  tag: string,
+  paths: [path: string, pathDef: PathItemObject][],
+  doc: OpenAPIObject,
+  componentByDef: { [def: string]: DefInfo }
+): void {
+  const importFiles: { [filename: string]: Set<string> } = {};
+
+  let server = doc.servers![0].url;
+  const prefix = getLongestCommonPrefix(paths.map((p) => p[0]));
+
+  const pathDefinitions = paths.map(([path, pathDef]) =>
+    generatePathDefinition(path, pathDef, doc, componentByDef, importFiles, prefix)
+  );
+
+  const filename = `generated-src/${tag.toLowerCase()}/api.ts`;
+
+  const imports = generateImports(filename, importFiles);
+
+  const apiBase = `const API_BASE = "${server}${prefix}";`;
+
+  const definition =
+    [
+      generateHeader(doc),
+      httpClientType,
+      imports,
+      prefix.length > 0 ? apiBase : undefined,
+      ...pathDefinitions,
+    ]
+      .filter(Boolean)
+      .join('\n\n') + '\n';
+
+  writeOutFile(filename, definition);
+}
+
+/**
+ * Generate a properly typed function for the API implementation, that will pass the correct parameters
+ * to the HTTP client.
+ *
+ * Example:
+ *
+ * export function getVendors(http: HttpClient, params: GetVendorsParams): Promise<ServerResponse<DestinyVendorsResponse>> {
+ *   return http({
+ *     method: 'GET',
+ *     url: `https://www.bungie.net/Platform/Destiny2/${params.membershipType}/Profile/${params.destinyMembershipId}/Character/${params.characterId}/Vendors/`,
+ *     params: {
+ *       components: params.components?.join(','),
+ *       filter: params.filter
+ *     }
+ *   });
+ * }
+ */
+function generatePathDefinition(
+  /** The path specification for the API */
+  path: string,
+  /** OpenAPI information about the path object */
+  pathDef: PathItemObject,
+  /** The whole OpenAPI document */
+  doc: OpenAPIObject,
+  componentByDef: Readonly<{ [def: string]: DefInfo }>,
+  importFiles: { [filename: string]: Set<string> }, // mutated
+  pathPrefix: string
+) {
+  let server = doc.servers![0].url;
+  // per https://github.com/Bungie-net/api/issues/853
+  // strict condition, so no surprises if doc.servers changes
+  let usePathPrefix = pathPrefix.length > 0;
+  if (
+    server === 'https://www.bungie.net/Platform' &&
+    path.includes('/Stats/PostGameCarnageReport/')
+  ) {
+    server = 'https://stats.bungie.net/Platform';
+    usePathPrefix = false;
+  }
+
+  if (usePathPrefix) {
+    path = path.substring(pathPrefix.length);
+  }
+
+  const interfaceName = lastPart(pathDef.summary!);
+  const functionName = lcFirst(interfaceName);
+
+  const method = pathDef.get ? 'GET' : 'POST';
+  const methodDef = pathDef.get || pathDef.post!;
+  const params = (methodDef.parameters || []) as ParameterObject[];
+
+  const queryParameterNames = params
+    .filter((param) => param.in === 'query')
+    .map((param) => param.name);
+
+  const parameterArgs: string[] = [`http: HttpClient`];
+
+  let interfaceDefinition = '';
+  if (params.length) {
+    interfaceDefinition =
+      generateInterfaceSchema(interfaceName + 'Params', params, doc, componentByDef, importFiles) +
+      '\n\n';
+    parameterArgs.push(`params: ${interfaceName}Params`);
+  }
+
+  if (methodDef.requestBody) {
+    if (isRequestBodyObject(methodDef.requestBody)) {
+      const schema = methodDef.requestBody.content['application/json'].schema!;
+
+      const paramType = resolveSchemaType(schema, doc);
+      addImport(doc, schema, componentByDef, importFiles);
+      const docString = methodDef.requestBody.description
+        ? docComment(methodDef.requestBody.description) + '\n'
+        : '';
+      parameterArgs.push(
+        `${docString}body${methodDef.requestBody.required ? '' : '?'}: ${paramType}`
+      );
+    } else if (isReferenceObject(methodDef.requestBody)) {
+      throw new Error("didn't expect this");
+    }
+  }
+
+  const templatizedPath = `\`${usePathPrefix ? '${API_BASE}' : server}${path.replace(
+    /{/g,
+    '${params.'
+  )}\``;
+
+  let paramsObject = '';
+  if (queryParameterNames.length) {
+    const paramInitializers = queryParameterNames.map((p) => {
+      const param = params.find((pa) => pa.name === p)!;
+      const paramType = resolveSchemaType(param.schema!, doc);
+
+      if (paramType.endsWith('[]')) {
+        if (!param.required) {
+          return `if (params.${p}?.length) { strParams.${p} = params.${p}.join(','); }`;
+        }
+        return `strParams.${p} = params.${p}.join(',');`;
+      }
+
+      return param.required
+        ? `strParams.${p} = params.${p}.toString();`
+        : `if (params.${p} !== undefined) { strParams.${p} = params.${p}${
+            paramType === 'string' ? '' : '.toString()'
+          }; }`;
+    });
+
+    paramsObject = `const strParams: Record<string, string> = {};
+${indent(paramInitializers.join('\n'), 1)}
+  `;
+  }
+
+  let requestBodyParam = '';
+  if (methodDef.requestBody && isRequestBodyObject(methodDef.requestBody)) {
+    requestBodyParam = ', body';
+  }
+
+  const returnValue = resolveSchemaType(methodDef.responses['200'], doc);
+  addImport(doc, methodDef.responses['200'], componentByDef, importFiles);
+
+  const rateDoc =
+    methodDef['x-documentation-attributes']?.ThrottleSecondsBetweenActionPerUser &&
+    `Wait at least ${methodDef['x-documentation-attributes']?.ThrottleSecondsBetweenActionPerUser}s between actions.`;
+
+  const fnBody =
+    method == 'GET'
+      ? `${paramsObject}return get(http, ${templatizedPath}${
+          paramsObject.length ? ', strParams' : ''
+        })`
+      : `  return post(http, ${templatizedPath}${requestBodyParam})`;
+
+  return `${interfaceDefinition}${docComment(
+    methodDef.description! + (rateDoc ? '\n' + rateDoc : '')
+  )}
+export function ${functionName}(${parameterArgs.join(', ')}): Promise<${returnValue}> {
+  ${fnBody};
+}`;
+}
+
+function generateInterfaceSchema(
+  interfaceName: string,
+  params: ParameterObject[],
+  doc: OpenAPIObject,
+  componentByDef: { [def: string]: DefInfo },
+  importFiles: { [filename: string]: Set<string> }
+) {
+  const parameterArgs = params.map((param) => {
+    // TODO: in general, need something that returns a type object
+    const paramType = resolveSchemaType(param.schema!, doc);
+    addImport(doc, param.schema!, componentByDef, importFiles);
+    const docString = param.description ? docComment(param.description) + '\n' : '';
+    return `${docString}${param.name}${
+      param.required || (param.name === 'components' && paramType === 'DestinyComponentType[]')
+        ? ''
+        : '?'
+    }: ${paramType};`;
+  });
+
+  return `export interface ${interfaceName} {
+${indent(parameterArgs.join('\n'), 1)}
+}`;
+}
+
+/**
+ * Find the longest prefix for a list of strings.
+ *
+ * @example
+ *
+ * // Returns "/Destiny2/"
+ * getLongestCommonPrefix("Destiny2/Clan/{groupId}/WeeklyRewardState/", "/Destiny2/Clan/ClanBannerDictionary/", "/Destiny2/{membershipType}/Profile/{destinyMembershipId}/Character/{characterId}/")
+ */
+function getLongestCommonPrefix(paths: string[]) {
+  if (paths.length < 2) {
+    return '';
+  }
+
+  let prefixLetters = '';
+
+  let index = 0;
+  for (const letter of paths[0]) {
+    if (letter === '{') {
+      break;
+    }
+    for (const path of paths) {
+      if (path[index] !== letter) {
+        return prefixLetters;
+      }
+    }
+    prefixLetters = prefixLetters.concat(letter);
+    index++;
+  }
+
+  return prefixLetters;
+}