/**
 * シルギア 郵便番号API v1 の型定義
 * https://api.shirugear.com/zip/
 *
 * 互換の方針: v1 の中では項目を「足す」ことはあっても、名前や意味は変えません。
 * 知らない項目が増えていても無視してください。
 */

/** 郵便番号の種類。area=地域の番号 / office=大口事業所の個別番号 / pobox=私書箱 */
export type ZipKind = "area" | "office" | "pobox";

/** GET /zip/v1/{郵便番号7桁}.json の results の1件 */
export interface ZipResult {
  kind: ZipKind;
  /** 都道府県コード（2桁。JIS X 0401。"01" 北海道 〜 "47" 沖縄県） */
  prefcode: string;
  /** 全国地方公共団体コード（5桁。市区町村を表す） */
  jiscode: string;
  prefecture: string;
  /** 全角カタカナ。事業所の番号で地域データから補えないときは null */
  prefecture_kana: string | null;
  city: string;
  /** 全角カタカナ。事業所の番号で地域データから補えないときは null */
  city_kana: string | null;
  /** 町域名。「以下に掲載がない場合」など町域が決まらない番号では ""（空文字） */
  town: string;
  /** 全角カタカナ（全角数字を含むことがある）。town が "" なら ""。事業所で補えないときは null */
  town_kana: string | null;
  /** 町域の注記（「１〜１９丁目」「次のビルを除く」「１階」など）。無ければ null。office / pobox では常に null */
  note: string | null;
  /** 番地以降（office / pobox のみ。area では null） */
  street: string | null;
  /** 事業所名（office / pobox のみ。area では null） */
  office_name: string | null;
  /** 事業所名のカナ（全角。小さい「ャ」なども大きい字のまま。office / pobox のみ） */
  office_name_kana: string | null;
  /** 取り扱う郵便局（office / pobox のみ） */
  post_office: string | null;
}

/** 廃止された郵便番号の案内（2023年7月以降。事業所の番号は2023年10月以降） */
export interface ZipAbolished {
  /** 廃止された年月 "YYYY-MM" */
  month: string;
  /** 廃止される前の住所 */
  previous: Array<{
    kind: ZipKind;
    prefecture: string;
    city: string;
    town: string;
    office_name: string | null;
  }>;
  /** 移った先と考えられる郵便番号（同じ月に同じ町域・同じ事業所名で追加された番号からの推定）。分からなければ [] */
  new_zipcodes: string[];
}

/** GET /zip/v1/{郵便番号7桁}.json */
export interface ZipResponse {
  zipcode: string;
  /** 地域の番号 → 事業所の番号 の順。廃止された番号では [] */
  results: ZipResult[];
  /** 廃止された番号のときだけ入る。それ以外は null */
  abolished: ZipAbolished | null;
  /** 取り込んだ日本郵便のデータの月 "YYYY-MM" */
  data_version: string;
}

/** GET /zip/v1/pref/{都道府県コード2桁}.json */
export interface PrefResponse {
  prefcode: string;
  prefecture: string;
  prefecture_kana: string;
  /** 全国地方公共団体コードの順 */
  cities: Array<{ jiscode: string; city: string; city_kana: string }>;
  data_version: string;
}

/** GET /zip/v1/city/{全国地方公共団体コード5桁}.json */
export interface CityResponse {
  jiscode: string;
  prefcode: string;
  prefecture: string;
  prefecture_kana: string;
  city: string;
  city_kana: string;
  /**
   * 地域の番号の町域の一覧（事業所の番号は含まない）。日本郵便のデータの並び（おおむね町域のカナ順）。
   * 同じ町域名が別の番号で何度も出ることがある（注記で分かれている）。
   */
  towns: Array<{ zipcode: string; town: string; town_kana: string; note: string | null }>;
  data_version: string;
}

/** GET /zip/v1/meta.json */
export interface MetaResponse {
  data_version: string;
  /** データを作った日時（ISO 8601・UTC） */
  built_at: string;
  source: string;
  counts: {
    /** 住所が返る郵便番号の数（地域＋事業所。廃止された番号は含まない） */
    zipcodes: number;
    /** 地域の番号の行数（1つの番号に町域が複数あれば複数行） */
    areas: number;
    /** 事業所・私書箱の番号の行数 */
    offices: number;
    /** 廃止された番号の数 */
    abolished: number;
  };
}

/** エラーのときの本文 */
export interface ErrorResponse {
  error: {
    status: 400 | 404 | 405;
    code:
      | "invalid_zipcode"
      | "invalid_prefcode"
      | "invalid_jiscode"
      | "invalid_request"
      | "zipcode_not_found"
      | "prefcode_not_found"
      | "jiscode_not_found"
      | "not_found"
      | "method_not_allowed";
    message: string;
  };
}