keyboard/keyBoard/Class/Network/KBNetworkManager.h

//
//  KBNetworkManager.h
//  CustomKeyboard
//
//  轻量网络层封装（扩展安全）。支持 GET/POST(JSON)。
//  注意：键盘扩展需要"允许完全访问"后才可联网，
//  建议由宿主控制器在确认后调用 `setEnabled:YES` 再发起请求。
//

#import <Foundation/Foundation.h>

NS_ASSUME_NONNULL_BEGIN

extern NSErrorDomain const KBNetworkErrorDomain;
typedef NS_ERROR_ENUM(KBNetworkErrorDomain, KBNetworkError) {
    KBNetworkErrorDisabled = 1,   // 未启用网络（例如未开启完全访问）
    KBNetworkErrorInvalidURL = 2,
    KBNetworkErrorInvalidResponse = 3,
    KBNetworkErrorDecodeFailed = 4,
    KBNetworkErrorBusiness     = 5, // 服务端返回非成功业务 code
};

/// JSON 回调：约定服务端统一返回顶层 NSDictionary（{code,message,data,...}）
typedef void(^KBNetworkCompletion)(NSDictionary *_Nullable json,
                                   NSURLResponse *_Nullable response,
                                   NSError *_Nullable error);

/// 二进制回调：用于下载 zip、图片等原始数据
typedef void(^KBNetworkDataCompletion)(NSData *_Nullable data,
                                       NSURLResponse *_Nullable response,
                                       NSError *_Nullable error);

@interface KBNetworkManager : NSObject

/// 单例
+ (instancetype)shared;

/// 是否允许网络（默认为 NO，宿主在合适时机置 YES）
@property (atomic, assign, getter=isEnabled) BOOL enabled;

/// 可选的基础域名，例如 https://api.example.com
@property (nonatomic, strong, nullable) NSURL *baseURL;

/// 全局默认请求头（每次请求会与局部 headers 合并，局部优先）
@property (nonatomic, copy) NSDictionary<NSString *, NSString *> *defaultHeaders;

/// 超时时间（默认 10s）
@property (nonatomic, assign) NSTimeInterval timeout;

/// GET 请求，parameters 会拼到 URL 上
- (nullable NSURLSessionDataTask *)GET:(NSString *)path
                             parameters:(nullable NSDictionary *)parameters
                                headers:(nullable NSDictionary<NSString *, NSString *> *)headers
                   autoShowBusinessError:(BOOL)autoShowBusinessError
                              completion:(KBNetworkCompletion)completion;

/// 兼容旧调用：默认 autoShowBusinessError = YES
- (nullable NSURLSessionDataTask *)GET:(NSString *)path
                             parameters:(nullable NSDictionary *)parameters
                                headers:(nullable NSDictionary<NSString *, NSString *> *)headers
                              completion:(KBNetworkCompletion)completion;

/// GET 原始二进制数据（不做 JSON 解析/业务 code 处理）
- (nullable NSURLSessionDataTask *)GETData:(NSString *)path
                                 parameters:(nullable NSDictionary *)parameters
                                    headers:(nullable NSDictionary<NSString *, NSString *> *)headers
                                  completion:(KBNetworkDataCompletion)completion;

/// POST JSON 请求，jsonBody 会以 application/json 发送
- (nullable NSURLSessionDataTask *)POST:(NSString *)path
                               jsonBody:(nullable id)jsonBody
                                headers:(nullable NSDictionary<NSString *, NSString *> *)headers
                   autoShowBusinessError:(BOOL)autoShowBusinessError
                              completion:(KBNetworkCompletion)completion;

/// 兼容旧调用：默认 autoShowBusinessError = YES
- (nullable NSURLSessionDataTask *)POST:(NSString *)path
                               jsonBody:(nullable id)jsonBody
                                headers:(nullable NSDictionary<NSString *, NSString *> *)headers
                              completion:(KBNetworkCompletion)completion;

@end

NS_ASSUME_NONNULL_END